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 - 2010, 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 /// MD5 digest size in bytes
  23 ///
  24 #define MD5_DIGEST_SIZE     16
  25
  26 ///
  27 /// SHA-1 digest size in bytes.
  28 ///
  29 #define SHA1_DIGEST_SIZE    20
  30
  31 ///
  32 /// SHA-256 digest size in bytes
  33 ///
  34 #define SHA256_DIGEST_SIZE  32
  35
  36 ///
  37 /// TDES block size in bytes
  38 ///
  39 #define TDES_BLOCK_SIZE     8
  40
  41 ///
  42 /// AES block size in bytes
  43 ///
  44 #define AES_BLOCK_SIZE      16
  45
  46 ///
  47 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
  48 ///
  49 typedef enum {
  50   RsaKeyN,      ///< RSA public Modulus (N)
  51   RsaKeyE,      ///< RSA Public exponent (e)
  52   RsaKeyD,      ///< RSA Private exponent (d)
  53   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)
  54   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)
  55   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))
  56   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))
  57   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)
  58 } RSA_KEY_TAG;
  59
  60 //=====================================================================================
  61 //    One-Way Cryptographic Hash Primitives
  62 //=====================================================================================
  63
  64 /**
  65   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
  66
  67   @return  The size, in bytes, of the context buffer required for MD5 hash operations.
  68
  69 **/
  70 UINTN
  71 EFIAPI
  72 Md5GetContextSize (
  73   VOID
  74   );
  75
  76 /**
  77   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
  78   subsequent use.
  79
  80   If Md5Context is NULL, then ASSERT().
  81
  82   @param[out]  Md5Context  Pointer to MD5 context being initialized.
  83
  84   @retval TRUE   MD5 context initialization succeeded.
  85   @retval FALSE  MD5 context initialization failed.
  86
  87 **/
  88 BOOLEAN
  89 EFIAPI
  90 Md5Init (
  91   OUT  VOID  *Md5Context
  92   );
  93
  94 /**
  95   Makes a copy of an existing MD5 context.
  96
  97   If Md5Context is NULL, then ASSERT().
  98   If NewMd5Context is NULL, then ASSERT().
  99
 100   @param[in]  Md5Context     Pointer to MD5 context being copied.
 101   @param[out] NewMd5Context  Pointer to new MD5 context.
 102
 103   @retval TRUE   MD5 context copy succeeded.
 104   @retval FALSE  MD5 context copy failed.
 105
 106 **/
 107 BOOLEAN
 108 EFIAPI
 109 Md5Duplicate (
 110   IN   CONST VOID  *Md5Context,
 111   OUT  VOID        *NewMd5Context
 112   );
 113
 114 /**
 115   Digests the input data and updates MD5 context.
 116
 117   This function performs MD5 digest on a data buffer of the specified size.
 118   It can be called multiple times to compute the digest of long or discontinuous data streams.
 119   MD5 context should be already correctly intialized by Md5Init(), and should not be finalized
 120   by Md5Final(). Behavior with invalid context is undefined.
 121
 122   If Md5Context is NULL, then ASSERT().
 123
 124   @param[in, out]  Md5Context  Pointer to the MD5 context.
 125   @param[in]       Data        Pointer to the buffer containing the data to be hashed.
 126   @param[in]       DataSize    Size of Data buffer in bytes.
 127
 128   @retval TRUE   MD5 data digest succeeded.
 129   @retval FALSE  MD5 data digest failed.
 130
 131 **/
 132 BOOLEAN
 133 EFIAPI
 134 Md5Update (
 135   IN OUT  VOID        *Md5Context,
 136   IN      CONST VOID  *Data,
 137   IN      UINTN       DataSize
 138   );
 139
 140 /**
 141   Completes computation of the MD5 digest value.
 142
 143   This function completes MD5 hash computation and retrieves the digest value into
 144   the specified memory. After this function has been called, the MD5 context cannot
 145   be used again.
 146   MD5 context should be already correctly intialized by Md5Init(), and should not be
 147   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.
 148
 149   If Md5Context is NULL, then ASSERT().
 150   If HashValue is NULL, then ASSERT().
 151
 152   @param[in, out]  Md5Context  Pointer to the MD5 context.
 153   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest
 154                                value (16 bytes).
 155
 156   @retval TRUE   MD5 digest computation succeeded.
 157   @retval FALSE  MD5 digest computation failed.
 158
 159 **/
 160 BOOLEAN
 161 EFIAPI
 162 Md5Final (
 163   IN OUT  VOID   *Md5Context,
 164   OUT     UINT8  *HashValue
 165   );
 166
 167 /**
 168   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
 169
 170   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.
 171
 172 **/
 173 UINTN
 174 EFIAPI
 175 Sha1GetContextSize (
 176   VOID
 177   );
 178
 179 /**
 180   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
 181   subsequent use.
 182
 183   If Sha1Context is NULL, then ASSERT().
 184
 185   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.
 186
 187   @retval TRUE   SHA-1 context initialization succeeded.
 188   @retval FALSE  SHA-1 context initialization failed.
 189
 190 **/
 191 BOOLEAN
 192 EFIAPI
 193 Sha1Init (
 194   OUT  VOID  *Sha1Context
 195   );
 196
 197 /**
 198   Makes a copy of an existing SHA-1 context.
 199
 200   If Sha1Context is NULL, then ASSERT().
 201   If NewSha1Context is NULL, then ASSERT().
 202
 203   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.
 204   @param[out] NewSha1Context  Pointer to new SHA-1 context.
 205
 206   @retval TRUE   SHA-1 context copy succeeded.
 207   @retval FALSE  SHA-1 context copy failed.
 208
 209 **/
 210 BOOLEAN
 211 EFIAPI
 212 Sha1Duplicate (
 213   IN   CONST VOID  *Sha1Context,
 214   OUT  VOID        *NewSha1Context
 215   );
 216
 217 /**
 218   Digests the input data and updates SHA-1 context.
 219
 220   This function performs SHA-1 digest on a data buffer of the specified size.
 221   It can be called multiple times to compute the digest of long or discontinuous data streams.
 222   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized
 223   by Sha1Final(). Behavior with invalid context is undefined.
 224
 225   If Sha1Context is NULL, then ASSERT().
 226
 227   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 228   @param[in]       Data         Pointer to the buffer containing the data to be hashed.
 229   @param[in]       DataSize     Size of Data buffer in bytes.
 230
 231   @retval TRUE   SHA-1 data digest succeeded.
 232   @retval FALSE  SHA-1 data digest failed.
 233
 234 **/
 235 BOOLEAN
 236 EFIAPI
 237 Sha1Update (
 238   IN OUT  VOID        *Sha1Context,
 239   IN      CONST VOID  *Data,
 240   IN      UINTN       DataSize
 241   );
 242
 243 /**
 244   Completes computation of the SHA-1 digest value.
 245
 246   This function completes SHA-1 hash computation and retrieves the digest value into
 247   the specified memory. After this function has been called, the SHA-1 context cannot
 248   be used again.
 249   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be
 250   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
 251
 252   If Sha1Context is NULL, then ASSERT().
 253   If HashValue is NULL, then ASSERT().
 254
 255   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 256   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest
 257                                 value (20 bytes).
 258
 259   @retval TRUE   SHA-1 digest computation succeeded.
 260   @retval FALSE  SHA-1 digest computation failed.
 261
 262 **/
 263 BOOLEAN
 264 EFIAPI
 265 Sha1Final (
 266   IN OUT  VOID   *Sha1Context,
 267   OUT     UINT8  *HashValue
 268   );
 269
 270 /**
 271   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
 272
 273   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.
 274
 275 **/
 276 UINTN
 277 EFIAPI
 278 Sha256GetContextSize (
 279   VOID
 280   );
 281
 282 /**
 283   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
 284   subsequent use.
 285
 286   If Sha256Context is NULL, then ASSERT().
 287
 288   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.
 289
 290   @retval TRUE   SHA-256 context initialization succeeded.
 291   @retval FALSE  SHA-256 context initialization failed.
 292
 293 **/
 294 BOOLEAN
 295 EFIAPI
 296 Sha256Init (
 297   OUT  VOID  *Sha256Context
 298   );
 299
 300 /**
 301   Makes a copy of an existing SHA-256 context.
 302
 303   If Sha256Context is NULL, then ASSERT().
 304   If NewSha256Context is NULL, then ASSERT().
 305
 306   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.
 307   @param[out] NewSha256Context  Pointer to new SHA-256 context.
 308
 309   @retval TRUE   SHA-256 context copy succeeded.
 310   @retval FALSE  SHA-256 context copy failed.
 311
 312 **/
 313 BOOLEAN
 314 EFIAPI
 315 Sha256Duplicate (
 316   IN   CONST VOID  *Sha256Context,
 317   OUT  VOID        *NewSha256Context
 318   );
 319
 320 /**
 321   Digests the input data and updates SHA-256 context.
 322
 323   This function performs SHA-256 digest on a data buffer of the specified size.
 324   It can be called multiple times to compute the digest of long or discontinuous data streams.
 325   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized
 326   by Sha256Final(). Behavior with invalid context is undefined.
 327
 328   If Sha256Context is NULL, then ASSERT().
 329
 330   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 331   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 332   @param[in]       DataSize       Size of Data buffer in bytes.
 333
 334   @retval TRUE   SHA-256 data digest succeeded.
 335   @retval FALSE  SHA-256 data digest failed.
 336
 337 **/
 338 BOOLEAN
 339 EFIAPI
 340 Sha256Update (
 341   IN OUT  VOID        *Sha256Context,
 342   IN      CONST VOID  *Data,
 343   IN      UINTN       DataSize
 344   );
 345
 346 /**
 347   Completes computation of the SHA-256 digest value.
 348
 349   This function completes SHA-256 hash computation and retrieves the digest value into
 350   the specified memory. After this function has been called, the SHA-256 context cannot
 351   be used again.
 352   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be
 353   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
 354
 355   If Sha256Context is NULL, then ASSERT().
 356   If HashValue is NULL, then ASSERT().
 357
 358   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 359   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest
 360                                   value (32 bytes).
 361
 362   @retval TRUE   SHA-256 digest computation succeeded.
 363   @retval FALSE  SHA-256 digest computation failed.
 364
 365 **/
 366 BOOLEAN
 367 EFIAPI
 368 Sha256Final (
 369   IN OUT  VOID   *Sha256Context,
 370   OUT     UINT8  *HashValue
 371   );
 372
 373
 374 //=====================================================================================
 375 //    MAC (Message Authentication Code) Primitive
 376 //=====================================================================================
 377
 378 /**
 379   Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.
 380
 381   @return  The size, in bytes, of the context buffer required for HMAC-MD5 operations.
 382
 383 **/
 384 UINTN
 385 EFIAPI
 386 HmacMd5GetContextSize (
 387   VOID
 388   );
 389
 390 /**
 391   Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for
 392   subsequent use.
 393
 394   If HmacMd5Context is NULL, then ASSERT().
 395
 396   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context being initialized.
 397   @param[in]   Key             Pointer to the user-supplied key.
 398   @param[in]   KeySize         Key size in bytes.
 399
 400   @retval TRUE   HMAC-MD5 context initialization succeeded.
 401   @retval FALSE  HMAC-MD5 context initialization failed.
 402
 403 **/
 404 BOOLEAN
 405 EFIAPI
 406 HmacMd5Init (
 407   OUT  VOID         *HmacMd5Context,
 408   IN   CONST UINT8  *Key,
 409   IN   UINTN        KeySize
 410   );
 411
 412 /**
 413   Makes a copy of an existing HMAC-MD5 context.
 414
 415   If HmacMd5Context is NULL, then ASSERT().
 416   If NewHmacMd5Context is NULL, then ASSERT().
 417
 418   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.
 419   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.
 420
 421   @retval TRUE   HMAC-MD5 context copy succeeded.
 422   @retval FALSE  HMAC-MD5 context copy failed.
 423
 424 **/
 425 BOOLEAN
 426 EFIAPI
 427 HmacMd5Duplicate (
 428   IN   CONST VOID  *HmacMd5Context,
 429   OUT  VOID        *NewHmacMd5Context
 430   );
 431
 432 /**
 433   Digests the input data and updates HMAC-MD5 context.
 434
 435   This function performs HMAC-MD5 digest on a data buffer of the specified size.
 436   It can be called multiple times to compute the digest of long or discontinuous data streams.
 437   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be
 438   finalized by HmacMd5Final(). Behavior with invalid context is undefined.
 439
 440   If HmacMd5Context is NULL, then ASSERT().
 441
 442   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
 443   @param[in]       Data            Pointer to the buffer containing the data to be digested.
 444   @param[in]       DataSize        Size of Data buffer in bytes.
 445
 446   @retval TRUE   HMAC-MD5 data digest succeeded.
 447   @retval FALSE  HMAC-MD5 data digest failed.
 448
 449 **/
 450 BOOLEAN
 451 EFIAPI
 452 HmacMd5Update (
 453   IN OUT  VOID        *HmacMd5Context,
 454   IN      CONST VOID  *Data,
 455   IN      UINTN       DataSize
 456   );
 457
 458 /**
 459   Completes computation of the HMAC-MD5 digest value.
 460
 461   This function completes HMAC-MD5 hash computation and retrieves the digest value into
 462   the specified memory. After this function has been called, the HMAC-MD5 context cannot
 463   be used again.
 464   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be
 465   finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.
 466
 467   If HmacMd5Context is NULL, then ASSERT().
 468   If HashValue is NULL, then ASSERT().
 469
 470   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
 471   @param[out]      HashValue       Pointer to a buffer that receives the HMAC-MD5 digest
 472                                    value (16 bytes).
 473
 474   @retval TRUE   HMAC-MD5 digest computation succeeded.
 475   @retval FALSE  HMAC-MD5 digest computation failed.
 476
 477 **/
 478 BOOLEAN
 479 EFIAPI
 480 HmacMd5Final (
 481   IN OUT  VOID   *HmacMd5Context,
 482   OUT     UINT8  *HmacValue
 483   );
 484
 485 /**
 486   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.
 487
 488   @return  The size, in bytes, of the context buffer required for HMAC-SHA1 operations.
 489
 490 **/
 491 UINTN
 492 EFIAPI
 493 HmacSha1GetContextSize (
 494   VOID
 495   );
 496
 497 /**
 498   Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for
 499   subsequent use.
 500
 501   If HmacSha1Context is NULL, then ASSERT().
 502
 503   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context being initialized.
 504   @param[in]   Key              Pointer to the user-supplied key.
 505   @param[in]   KeySize          Key size in bytes.
 506
 507   @retval TRUE   HMAC-SHA1 context initialization succeeded.
 508   @retval FALSE  HMAC-SHA1 context initialization failed.
 509
 510 **/
 511 BOOLEAN
 512 EFIAPI
 513 HmacSha1Init (
 514   OUT  VOID         *HmacSha1Context,
 515   IN   CONST UINT8  *Key,
 516   IN   UINTN        KeySize
 517   );
 518
 519 /**
 520   Makes a copy of an existing HMAC-SHA1 context.
 521
 522   If HmacSha1Context is NULL, then ASSERT().
 523   If NewHmacSha1Context is NULL, then ASSERT().
 524
 525   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.
 526   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.
 527
 528   @retval TRUE   HMAC-SHA1 context copy succeeded.
 529   @retval FALSE  HMAC-SHA1 context copy failed.
 530
 531 **/
 532 BOOLEAN
 533 EFIAPI
 534 HmacSha1Duplicate (
 535   IN   CONST VOID  *HmacSha1Context,
 536   OUT  VOID        *NewHmacSha1Context
 537   );
 538
 539 /**
 540   Digests the input data and updates HMAC-SHA1 context.
 541
 542   This function performs HMAC-SHA1 digest on a data buffer of the specified size.
 543   It can be called multiple times to compute the digest of long or discontinuous data streams.
 544   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not
 545   be finalized by HmacSha1Final(). Behavior with invalid context is undefined.
 546
 547   If HmacSha1Context is NULL, then ASSERT().
 548
 549   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.
 550   @param[in]       Data            Pointer to the buffer containing the data to be digested.
 551   @param[in]       DataSize        Size of Data buffer in bytes.
 552
 553   @retval TRUE   HMAC-SHA1 data digest succeeded.
 554   @retval FALSE  HMAC-SHA1 data digest failed.
 555
 556 **/
 557 BOOLEAN
 558 EFIAPI
 559 HmacSha1Update (
 560   IN OUT  VOID        *HmacSha1Context,
 561   IN      CONST VOID  *Data,
 562   IN      UINTN       DataSize
 563   );
 564
 565 /**
 566   Completes computation of the HMAC-SHA1 digest value.
 567
 568   This function completes HMAC-SHA1 hash computation and retrieves the digest value into
 569   the specified memory. After this function has been called, the HMAC-SHA1 context cannot
 570   be used again.
 571   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should
 572   not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.
 573
 574   If HmacSha1Context is NULL, then ASSERT().
 575   If HashValue is NULL, then ASSERT().
 576
 577   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.
 578   @param[out]      HashValue        Pointer to a buffer that receives the HMAC-SHA1 digest
 579                                     value (20 bytes).
 580
 581   @retval TRUE   HMAC-SHA1 digest computation succeeded.
 582   @retval FALSE  HMAC-SHA1 digest computation failed.
 583
 584 **/
 585 BOOLEAN
 586 EFIAPI
 587 HmacSha1Final (
 588   IN OUT  VOID   *HmacSha1Context,
 589   OUT     UINT8  *HmacValue
 590   );
 591
 592
 593 //=====================================================================================
 594 //    Symmetric Cryptography Primitive
 595 //=====================================================================================
 596
 597 /**
 598   Retrieves the size, in bytes, of the context buffer required for TDES operations.
 599
 600   @return  The size, in bytes, of the context buffer required for TDES operations.
 601
 602 **/
 603 UINTN
 604 EFIAPI
 605 TdesGetContextSize (
 606   VOID
 607   );
 608
 609 /**
 610   Initializes user-supplied memory as TDES context for subsequent use.
 611
 612   This function initializes user-supplied memory pointed by TdesContext as TDES context.
 613   In addtion, it sets up all TDES key materials for subsequent encryption and decryption
 614   operations.
 615   There are 3 key options as follows:
 616   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)
 617   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)
 618   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)
 619
 620   If TdesContext is NULL, then ASSERT().
 621   If Key is NULL, then ASSERT().
 622   If KeyLength is not valid, then ASSERT().
 623
 624   @param[out]  TdesContext  Pointer to TDES context being initialized.
 625   @param[in]   Key          Pointer to the user-supplied TDES key.
 626   @param[in]   KeyLength    Length of TDES key in bits.
 627
 628   @retval TRUE   TDES context initialization succeeded.
 629   @retval FALSE  TDES context initialization failed.
 630
 631 **/
 632 BOOLEAN
 633 EFIAPI
 634 TdesInit (
 635   OUT  VOID         *TdesContext,
 636   IN   CONST UINT8  *Key,
 637   IN   UINTN        KeyLength
 638   );
 639
 640 /**
 641   Performs TDES encryption on a data buffer of the specified size in ECB mode.
 642
 643   This function performs TDES encryption on data buffer pointed by Input, of specified
 644   size of InputSize, in ECB mode.
 645   InputSize must be multiple of block size (8 bytes). This function does not perform
 646   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 647   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 648   invalid TDES context is undefined.
 649
 650   If TdesContext is NULL, then ASSERT().
 651   If Input is NULL, then ASSERT().
 652   If InputSize is not multiple of block size (8 bytes), then ASSERT().
 653   If Output is NULL, then ASSERT().
 654
 655   @param[in]   TdesContext  Pointer to the TDES context.
 656   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 657   @param[in]   InputSize    Size of the Input buffer in bytes.
 658   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 659
 660   @retval TRUE   TDES encryption succeeded.
 661   @retval FALSE  TDES encryption failed.
 662
 663 **/
 664 BOOLEAN
 665 EFIAPI
 666 TdesEcbEncrypt (
 667   IN   VOID         *TdesContext,
 668   IN   CONST UINT8  *Input,
 669   IN   UINTN        InputSize,
 670   OUT  UINT8        *Output
 671   );
 672
 673 /**
 674   Performs TDES decryption on a data buffer of the specified size in ECB mode.
 675
 676   This function performs TDES decryption on data buffer pointed by Input, of specified
 677   size of InputSize, in ECB mode.
 678   InputSize must be multiple of block size (8 bytes). This function does not perform
 679   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 680   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 681   invalid TDES context is undefined.
 682
 683   If TdesContext is NULL, then ASSERT().
 684   If Input is NULL, then ASSERT().
 685   If InputSize is not multiple of block size (8 bytes), then ASSERT().
 686   If Output is NULL, then ASSERT().
 687
 688   @param[in]   TdesContext  Pointer to the TDES context.
 689   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.
 690   @param[in]   InputSize    Size of the Input buffer in bytes.
 691   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.
 692
 693   @retval TRUE   TDES decryption succeeded.
 694   @retval FALSE  TDES decryption failed.
 695
 696 **/
 697 BOOLEAN
 698 EFIAPI
 699 TdesEcbDecrypt (
 700   IN   VOID         *TdesContext,
 701   IN   CONST UINT8  *Input,
 702   IN   UINTN        InputSize,
 703   OUT  UINT8        *Output
 704   );
 705
 706 /**
 707   Performs TDES encryption on a data buffer of the specified size in CBC mode.
 708
 709   This function performs TDES encryption on data buffer pointed by Input, of specified
 710   size of InputSize, in CBC mode.
 711   InputSize must be multiple of block size (8 bytes). This function does not perform
 712   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 713   Initialization vector should be one block size (8 bytes).
 714   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 715   invalid TDES context is undefined.
 716
 717   If TdesContext is NULL, then ASSERT().
 718   If Input is NULL, then ASSERT().
 719   If InputSize is not multiple of block size (8 bytes), then ASSERT().
 720   If Ivec is NULL, then ASSERT().
 721   If Output is NULL, then ASSERT().
 722
 723   @param[in]   TdesContext  Pointer to the TDES context.
 724   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 725   @param[in]   InputSize    Size of the Input buffer in bytes.
 726   @param[in]   Ivec         Pointer to initialization vector.
 727   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 728
 729   @retval TRUE   TDES encryption succeeded.
 730   @retval FALSE  TDES encryption failed.
 731
 732 **/
 733 BOOLEAN
 734 EFIAPI
 735 TdesCbcEncrypt (
 736   IN   VOID         *TdesContext,
 737   IN   CONST UINT8  *Input,
 738   IN   UINTN        InputSize,
 739   IN   CONST UINT8  *Ivec,
 740   OUT  UINT8        *Output
 741   );
 742
 743 /**
 744   Performs TDES decryption on a data buffer of the specified size in CBC mode.
 745
 746   This function performs TDES decryption on data buffer pointed by Input, of specified
 747   size of InputSize, in CBC mode.
 748   InputSize must be multiple of block size (8 bytes). This function does not perform
 749   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 750   Initialization vector should be one block size (8 bytes).
 751   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 752   invalid TDES context is undefined.
 753
 754   If TdesContext is NULL, then ASSERT().
 755   If Input is NULL, then ASSERT().
 756   If InputSize is not multiple of block size (8 bytes), then ASSERT().
 757   If Ivec is NULL, then ASSERT().
 758   If Output is NULL, then ASSERT().
 759
 760   @param[in]   TdesContext  Pointer to the TDES context.
 761   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 762   @param[in]   InputSize    Size of the Input buffer in bytes.
 763   @param[in]   Ivec         Pointer to initialization vector.
 764   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 765
 766   @retval TRUE   TDES decryption succeeded.
 767   @retval FALSE  TDES decryption failed.
 768
 769 **/
 770 BOOLEAN
 771 EFIAPI
 772 TdesCbcDecrypt (
 773   IN   VOID         *TdesContext,
 774   IN   CONST UINT8  *Input,
 775   IN   UINTN        InputSize,
 776   IN   CONST UINT8  *Ivec,
 777   OUT  UINT8        *Output
 778   );
 779
 780 /**
 781   Retrieves the size, in bytes, of the context buffer required for AES operations.
 782
 783   @return  The size, in bytes, of the context buffer required for AES operations.
 784
 785 **/
 786 UINTN
 787 EFIAPI
 788 AesGetContextSize (
 789   VOID
 790   );
 791
 792 /**
 793   Initializes user-supplied memory as AES context for subsequent use.
 794
 795   This function initializes user-supplied memory pointed by AesContext as AES context.
 796   In addtion, it sets up all AES key materials for subsequent encryption and decryption
 797   operations.
 798   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
 799
 800   If AesContext is NULL, then ASSERT().
 801   If Key is NULL, then ASSERT().
 802   If KeyLength is not valid, then ASSERT().
 803
 804   @param[out]  AesContext  Pointer to AES context being initialized.
 805   @param[in]   Key         Pointer to the user-supplied AES key.
 806   @param[in]   KeyLength   Length of AES key in bits.
 807
 808   @retval TRUE   AES context initialization succeeded.
 809   @retval FALSE  AES context initialization failed.
 810
 811 **/
 812 BOOLEAN
 813 EFIAPI
 814 AesInit (
 815   OUT  VOID         *AesContext,
 816   IN   CONST UINT8  *Key,
 817   IN   UINTN        KeyLength
 818   );
 819
 820 /**
 821   Performs AES encryption on a data buffer of the specified size in ECB mode.
 822
 823   This function performs AES encryption on data buffer pointed by Input, of specified
 824   size of InputSize, in ECB mode.
 825   InputSize must be multiple of block size (16 bytes). This function does not perform
 826   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 827   AesContext should be already correctly initialized by AesInit(). Behavior with
 828   invalid AES context is undefined.
 829
 830   If AesContext is NULL, then ASSERT().
 831   If Input is NULL, then ASSERT().
 832   If InputSize is not multiple of block size (16 bytes), then ASSERT().
 833   If Output is NULL, then ASSERT().
 834
 835   @param[in]   AesContext  Pointer to the AES context.
 836   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
 837   @param[in]   InputSize   Size of the Input buffer in bytes.
 838   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
 839
 840   @retval TRUE   AES encryption succeeded.
 841   @retval FALSE  AES encryption failed.
 842
 843 **/
 844 BOOLEAN
 845 EFIAPI
 846 AesEcbEncrypt (
 847   IN   VOID         *AesContext,
 848   IN   CONST UINT8  *Input,
 849   IN   UINTN        InputSize,
 850   OUT  UINT8        *Output
 851   );
 852
 853 /**
 854   Performs AES decryption on a data buffer of the specified size in ECB mode.
 855
 856   This function performs AES decryption on data buffer pointed by Input, of specified
 857   size of InputSize, in ECB mode.
 858   InputSize must be multiple of block size (16 bytes). This function does not perform
 859   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 860   AesContext should be already correctly initialized by AesInit(). Behavior with
 861   invalid AES context is undefined.
 862
 863   If AesContext is NULL, then ASSERT().
 864   If Input is NULL, then ASSERT().
 865   If InputSize is not multiple of block size (16 bytes), then ASSERT().
 866   If Output is NULL, then ASSERT().
 867
 868   @param[in]   AesContext  Pointer to the AES context.
 869   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.
 870   @param[in]   InputSize   Size of the Input buffer in bytes.
 871   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.
 872
 873   @retval TRUE   AES decryption succeeded.
 874   @retval FALSE  AES decryption failed.
 875
 876 **/
 877 BOOLEAN
 878 EFIAPI
 879 AesEcbDecrypt (
 880   IN   VOID         *AesContext,
 881   IN   CONST UINT8  *Input,
 882   IN   UINTN        InputSize,
 883   OUT  UINT8        *Output
 884   );
 885
 886 /**
 887   Performs AES encryption on a data buffer of the specified size in CBC mode.
 888
 889   This function performs AES encryption on data buffer pointed by Input, of specified
 890   size of InputSize, in CBC mode.
 891   InputSize must be multiple of block size (16 bytes). This function does not perform
 892   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 893   Initialization vector should be one block size (16 bytes).
 894   AesContext should be already correctly initialized by AesInit(). Behavior with
 895   invalid AES context is undefined.
 896
 897   If AesContext is NULL, then ASSERT().
 898   If Input is NULL, then ASSERT().
 899   If InputSize is not multiple of block size (16 bytes), then ASSERT().
 900   If Ivec is NULL, then ASSERT().
 901   If Output is NULL, then ASSERT().
 902
 903   @param[in]   AesContext  Pointer to the AES context.
 904   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
 905   @param[in]   InputSize   Size of the Input buffer in bytes.
 906   @param[in]   Ivec        Pointer to initialization vector.
 907   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
 908
 909   @retval TRUE   AES encryption succeeded.
 910   @retval FALSE  AES encryption failed.
 911
 912 **/
 913 BOOLEAN
 914 EFIAPI
 915 AesCbcEncrypt (
 916   IN   VOID         *AesContext,
 917   IN   CONST UINT8  *Input,
 918   IN   UINTN        InputSize,
 919   IN   CONST UINT8  *Ivec,
 920   OUT  UINT8        *Output
 921   );
 922
 923 /**
 924   Performs AES decryption on a data buffer of the specified size in CBC mode.
 925
 926   This function performs AES decryption on data buffer pointed by Input, of specified
 927   size of InputSize, in CBC mode.
 928   InputSize must be multiple of block size (16 bytes). This function does not perform
 929   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 930   Initialization vector should be one block size (16 bytes).
 931   AesContext should be already correctly initialized by AesInit(). Behavior with
 932   invalid AES context is undefined.
 933
 934   If AesContext is NULL, then ASSERT().
 935   If Input is NULL, then ASSERT().
 936   If InputSize is not multiple of block size (16 bytes), then ASSERT().
 937   If Ivec is NULL, then ASSERT().
 938   If Output is NULL, then ASSERT().
 939
 940   @param[in]   AesContext  Pointer to the AES context.
 941   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
 942   @param[in]   InputSize   Size of the Input buffer in bytes.
 943   @param[in]   Ivec        Pointer to initialization vector.
 944   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
 945
 946   @retval TRUE   AES decryption succeeded.
 947   @retval FALSE  AES decryption failed.
 948
 949 **/
 950 BOOLEAN
 951 EFIAPI
 952 AesCbcDecrypt (
 953   IN   VOID         *AesContext,
 954   IN   CONST UINT8  *Input,
 955   IN   UINTN        InputSize,
 956   IN   CONST UINT8  *Ivec,
 957   OUT  UINT8        *Output
 958   );
 959
 960 /**
 961   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.
 962
 963   @return  The size, in bytes, of the context buffer required for ARC4 operations.
 964
 965 **/
 966 UINTN
 967 EFIAPI
 968 Arc4GetContextSize (
 969   VOID
 970   );
 971
 972 /**
 973   Initializes user-supplied memory as ARC4 context for subsequent use.
 974
 975   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.
 976   In addtion, it sets up all ARC4 key materials for subsequent encryption and decryption
 977   operations.
 978
 979   If Arc4Context is NULL, then ASSERT().
 980   If Key is NULL, then ASSERT().
 981   If KeySize does not in the range of [5, 256] bytes, then ASSERT().
 982
 983   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.
 984   @param[in]   Key          Pointer to the user-supplied ARC4 key.
 985   @param[in]   KeySize      Size of ARC4 key in bytes.
 986
 987   @retval TRUE   ARC4 context initialization succeeded.
 988   @retval FALSE  ARC4 context initialization failed.
 989
 990 **/
 991 BOOLEAN
 992 EFIAPI
 993 Arc4Init (
 994   OUT  VOID         *Arc4Context,
 995   IN   CONST UINT8  *Key,
 996   IN   UINTN        KeySize
 997   );
 998
 999 /**
1000   Performs ARC4 encryption on a data buffer of the specified size.
1001
1002   This function performs ARC4 encryption on data buffer pointed by Input, of specified
1003   size of InputSize.
1004   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1005   invalid ARC4 context is undefined.
1006
1007   If Arc4Context is NULL, then ASSERT().
1008   If Input is NULL, then ASSERT().
1009   If Output is NULL, then ASSERT().
1010
1011   @param[in]   Arc4Context  Pointer to the ARC4 context.
1012   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
1013   @param[in]   InputSize    Size of the Input buffer in bytes.
1014   @param[out]  Output       Pointer to a buffer that receives the ARC4 encryption output.
1015
1016   @retval TRUE   ARC4 encryption succeeded.
1017   @retval FALSE  ARC4 encryption failed.
1018
1019 **/
1020 BOOLEAN
1021 EFIAPI
1022 Arc4Encrypt (
1023   IN OUT  VOID         *Arc4Context,
1024   IN      CONST UINT8  *Input,
1025   IN      UINTN        InputSize,
1026   OUT     UINT8        *Output
1027   );
1028
1029 /**
1030   Performs ARC4 decryption on a data buffer of the specified size.
1031
1032   This function performs ARC4 decryption on data buffer pointed by Input, of specified
1033   size of InputSize.
1034   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1035   invalid ARC4 context is undefined.
1036
1037   If Arc4Context is NULL, then ASSERT().
1038   If Input is NULL, then ASSERT().
1039   If Output is NULL, then ASSERT().
1040
1041   @param[in]   Arc4Context  Pointer to the ARC4 context.
1042   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.
1043   @param[in]   InputSize    Size of the Input buffer in bytes.
1044   @param[out]  Output       Pointer to a buffer that receives the ARC4 decryption output.
1045
1046   @retval TRUE   ARC4 decryption succeeded.
1047   @retval FALSE  ARC4 decryption failed.
1048
1049 **/
1050 BOOLEAN
1051 EFIAPI
1052 Arc4Decrypt (
1053   IN OUT  VOID   *Arc4Context,
1054   IN      UINT8  *Input,
1055   IN      UINTN  InputSize,
1056   OUT     UINT8  *Output
1057   );
1058
1059 /**
1060   Resets the ARC4 context to the initial state.
1061
1062   The function resets the ARC4 context to the state it had immediately after the
1063   ARC4Init() function call.
1064   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context
1065   should be already correctly initialized by ARC4Init().
1066
1067   If Arc4Context is NULL, then ASSERT().
1068
1069   @param[in, out]  Arc4Context  Pointer to the ARC4 context.
1070
1071   @retval TRUE   ARC4 reset succeeded.
1072   @retval FALSE  ARC4 reset failed.
1073
1074 **/
1075 BOOLEAN
1076 EFIAPI
1077 Arc4Reset (
1078   IN OUT  VOID  *Arc4Context
1079   );
1080
1081 //=====================================================================================
1082 //    Asymmetric Cryptography Primitive
1083 //=====================================================================================
1084
1085 /**
1086   Allocates and initializes one RSA context for subsequent use.
1087
1088   @return  Pointer to the RSA context that has been initialized.
1089            If the allocations fails, RsaNew() returns NULL.
1090
1091 **/
1092 VOID *
1093 EFIAPI
1094 RsaNew (
1095   VOID
1096   );
1097
1098 /**
1099   Release the specified RSA context.
1100
1101   If RsaContext is NULL, then ASSERT().
1102
1103   @param[in]  RsaContext  Pointer to the RSA context to be released.
1104
1105 **/
1106 VOID
1107 EFIAPI
1108 RsaFree (
1109   IN  VOID  *RsaContext
1110   );
1111
1112 /**
1113   Sets the tag-designated key component into the established RSA context.
1114
1115   This function sets the tag-designated RSA key component into the established
1116   RSA context from the user-specified non-negative integer (octet string format
1117   represented in RSA PKCS#1).
1118   If BigNumber is NULL, then the specified key componenet in RSA context is cleared.
1119
1120   If RsaContext is NULL, then ASSERT().
1121
1122   @param[in, out]  RsaContext  Pointer to RSA context being set.
1123   @param[in]       KeyTag      Tag of RSA key component being set.
1124   @param[in]       BigNumber   Pointer to octet integer buffer.
1125                                If NULL, then the specified key componenet in RSA
1126                                context is cleared.
1127   @param[in]       BnSize      Size of big number buffer in bytes.
1128                                If BigNumber is NULL, then it is ignored.
1129
1130   @retval  TRUE   RSA key component was set successfully.
1131   @retval  FALSE  Invalid RSA key component tag.
1132
1133 **/
1134 BOOLEAN
1135 EFIAPI
1136 RsaSetKey (
1137   IN OUT  VOID         *RsaContext,
1138   IN      RSA_KEY_TAG  KeyTag,
1139   IN      CONST UINT8  *BigNumber,
1140   IN      UINTN        BnSize
1141   );
1142
1143 /**
1144   Gets the tag-designated RSA key component from the established RSA context.
1145
1146   This function retrieves the tag-designated RSA key component from the
1147   established RSA context as a non-negative integer (octet string format
1148   represented in RSA PKCS#1).
1149   If specified key component has not been set or has been cleared, then returned
1150   BnSize is set to 0.
1151   If the BigNumber buffer is too small to hold the contents of the key, FALSE
1152   is returned and BnSize is set to the required buffer size to obtain the key.
1153
1154   If RsaContext is NULL, then ASSERT().
1155   If BnSize is NULL, then ASSERT().
1156   If BnSize is large enough but BigNumber is NULL, then ASSERT().
1157
1158   @param[in, out]  RsaContext  Pointer to RSA context being set.
1159   @param[in]       KeyTag      Tag of RSA key component being set.
1160   @param[out]      BigNumber   Pointer to octet integer buffer.
1161   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.
1162                                On output, the size of data returned in big number buffer in bytes.
1163
1164   @retval  TRUE   RSA key component was retrieved successfully.
1165   @retval  FALSE  Invalid RSA key component tag.
1166   @retval  FALSE  BnSize is too small.
1167
1168 **/
1169 BOOLEAN
1170 EFIAPI
1171 RsaGetKey (
1172   IN OUT  VOID         *RsaContext,
1173   IN      RSA_KEY_TAG  KeyTag,
1174   OUT     UINT8        *BigNumber,
1175   IN OUT  UINTN        *BnSize
1176   );
1177
1178 /**
1179   Generates RSA key components.
1180
1181   This function generates RSA key components. It takes RSA public exponent E and
1182   length in bits of RSA modulus N as input, and generates all key components.
1183   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1184
1185   Before this function can be invoked, pseudorandom number generator must be correctly
1186   initialized by RandomSeed().
1187
1188   If RsaContext is NULL, then ASSERT().
1189
1190   @param[in, out]  RsaContext           Pointer to RSA context being set.
1191   @param[in]       ModulusLength        Length of RSA modulus N in bits.
1192   @param[in]       PublicExponent       Pointer to RSA public exponent.
1193   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes.
1194
1195   @retval  TRUE   RSA key component was generated successfully.
1196   @retval  FALSE  Invalid RSA key component tag.
1197
1198 **/
1199 BOOLEAN
1200 EFIAPI
1201 RsaGenerateKey (
1202   IN OUT  VOID         *RsaContext,
1203   IN      UINTN        ModulusLength,
1204   IN      CONST UINT8  *PublicExponent,
1205   IN      UINTN        PublicExponentSize
1206   );
1207
1208 /**
1209   Validates key components of RSA context.
1210
1211   This function validates key compoents of RSA context in following aspects:
1212   - Whether p is a prime
1213   - Whether q is a prime
1214   - Whether n = p * q
1215   - Whether d*e = 1  mod lcm(p-1,q-1)
1216
1217   If RsaContext is NULL, then ASSERT().
1218
1219   @param[in]  RsaContext  Pointer to RSA context to check.
1220
1221   @retval  TRUE   RSA key components are valid.
1222   @retval  FALSE  RSA key components are not valid.
1223
1224 **/
1225 BOOLEAN
1226 EFIAPI
1227 RsaCheckKey (
1228   IN  VOID  *RsaContext
1229   );
1230
1231 /**
1232   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1233
1234   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1235   RSA PKCS#1.
1236   If the Signature buffer is too small to hold the contents of signature, FALSE
1237   is returned and SigSize is set to the required buffer size to obtain the signature.
1238
1239   If RsaContext is NULL, then ASSERT().
1240   If MessageHash is NULL, then ASSERT().
1241   If HashSize is not equal to the size of MD5, SHA-1, SHA-256, SHA-224, SHA-512 or SHA-384 digest, then ASSERT().
1242   If SigSize is large enough but Signature is NULL, then ASSERT().
1243
1244   @param[in]      RsaContext   Pointer to RSA context for signature generation.
1245   @param[in]      MessageHash  Pointer to octet message hash to be signed.
1246   @param[in]      HashSize     Size of the message hash in bytes.
1247   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1248   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.
1249                               On output, the size of data returned in Signature buffer in bytes.
1250
1251   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.
1252   @retval  FALSE  Signature generation failed.
1253   @retval  FALSE  SigSize is too small.
1254
1255 **/
1256 BOOLEAN
1257 EFIAPI
1258 RsaPkcs1Sign (
1259   IN      VOID         *RsaContext,
1260   IN      CONST UINT8  *MessageHash,
1261   IN      UINTN        HashSize,
1262   OUT     UINT8        *Signature,
1263   IN OUT  UINTN        *SigSize
1264   );
1265
1266 /**
1267   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1268   RSA PKCS#1.
1269
1270   If RsaContext is NULL, then ASSERT().
1271   If MessageHash is NULL, then ASSERT().
1272   If Signature is NULL, then ASSERT().
1273   If HashSize is not equal to the size of MD5, SHA-1, SHA-256, SHA-224, SHA-512 or SHA-384 digest, then ASSERT().
1274
1275   @param[in]  RsaContext   Pointer to RSA context for signature verification.
1276   @param[in]  MessageHash  Pointer to octet message hash to be checked.
1277   @param[in]  HashSize     Size of the message hash in bytes.
1278   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.
1279   @param[in]  SigSize      Size of signature in bytes.
1280
1281   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.
1282   @retval  FALSE  Invalid signature or invalid RSA context.
1283
1284 **/
1285 BOOLEAN
1286 EFIAPI
1287 RsaPkcs1Verify (
1288   IN  VOID         *RsaContext,
1289   IN  CONST UINT8  *MessageHash,
1290   IN  UINTN        HashSize,
1291   IN  UINT8        *Signature,
1292   IN  UINTN        SigSize
1293   );
1294
1295 /**
1296   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: Cryptographic
1297   Message Syntax Standard".
1298
1299   If P7Data is NULL, then ASSERT().
1300
1301   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
1302   @param[in]  P7Size       Size of the PKCS#7 message in bytes.
1303   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
1304                            is used for certificate chain verification.
1305   @param[in]  CertSize     Size of the trusted certificate in bytes.
1306   @param[in]  InData       Pointer to the content to be verified.
1307   @param[in]  DataSize     Size of InData in bytes.
1308
1309   @retval  TRUE  The specified PKCS#7 signed data is valid.
1310   @retval  FALSE Invalid PKCS#7 signed data.
1311
1312 **/
1313 BOOLEAN
1314 EFIAPI
1315 Pkcs7Verify (
1316   IN  CONST UINT8  *P7Data,
1317   IN  UINTN        P7Size,
1318   IN  CONST UINT8  *TrustedCert,
1319   IN  UINTN        CertSize,
1320   IN  CONST UINT8  *InData,
1321   IN  UINTN        DataSize
1322   );
1323
1324 //=====================================================================================
1325 //    DH Key Exchange Primitive
1326 //=====================================================================================
1327
1328 /**
1329   Allocates and Initializes one Diffie-Hellman Context for subsequent use.
1330
1331   @return  Pointer to the Diffie-Hellman Context that has been initialized.
1332            If the allocations fails, DhNew() returns NULL.
1333
1334 **/
1335 VOID *
1336 EFIAPI
1337 DhNew (
1338   VOID
1339   );
1340
1341 /**
1342   Release the specified DH context.
1343
1344   If DhContext is NULL, then ASSERT().
1345
1346   @param[in]  DhContext  Pointer to the DH context to be released.
1347
1348 **/
1349 VOID
1350 EFIAPI
1351 DhFree (
1352   IN  VOID  *DhContext
1353   );
1354
1355 /**
1356   Generates DH parameter.
1357
1358   Given generator g, and length of prime number p in bits, this function generates p,
1359   and sets DH context according to value of g and p.
1360
1361   Before this function can be invoked, pseudorandom number generator must be correctly
1362   initialized by RandomSeed().
1363
1364   If DhContext is NULL, then ASSERT().
1365   If Prime is NULL, then ASSERT().
1366
1367   @param[in, out]  DhContext    Pointer to the DH context.
1368   @param[in]       Generator    Value of generator.
1369   @param[in]       PrimeLength  Length in bits of prime to be generated.
1370   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.
1371
1372   @retval TRUE   DH pamameter generation succeeded.
1373   @retval FALSE  Value of Generator is not supported.
1374   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.
1375
1376 **/
1377 BOOLEAN
1378 EFIAPI
1379 DhGenerateParameter (
1380   IN OUT  VOID   *DhContext,
1381   IN      UINTN  Generator,
1382   IN      UINTN  PrimeLength,
1383   OUT     UINT8  *Prime
1384   );
1385
1386 /**
1387   Sets generator and prime parameters for DH.
1388
1389   Given generator g, and prime number p, this function and sets DH
1390   context accordingly.
1391
1392   If DhContext is NULL, then ASSERT().
1393   If Prime is NULL, then ASSERT().
1394
1395   @param[in, out]  DhContext    Pointer to the DH context.
1396   @param[in]       Generator    Value of generator.
1397   @param[in]       PrimeLength  Length in bits of prime to be generated.
1398   @param[in]       Prime        Pointer to the prime number.
1399
1400   @retval TRUE   DH pamameter setting succeeded.
1401   @retval FALSE  Value of Generator is not supported.
1402   @retval FALSE  Value of Generator is not suitable for the Prime.
1403   @retval FALSE  Value of Prime is not a prime number.
1404   @retval FALSE  Value of Prime is not a safe prime number.
1405
1406 **/
1407 BOOLEAN
1408 EFIAPI
1409 DhSetParameter (
1410   IN OUT  VOID         *DhContext,
1411   IN      UINTN        Generator,
1412   IN      UINTN        PrimeLength,
1413   IN      CONST UINT8  *Prime
1414   );
1415
1416 /**
1417   Generates DH public key.
1418
1419   This function generates random secret exponent, and computes the public key, which is
1420   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
1421   If the PublicKey buffer is too small to hold the public key, FALSE is returned and
1422   PublicKeySize is set to the required buffer size to obtain the public key.
1423
1424   If DhContext is NULL, then ASSERT().
1425   If PublicKeySize is NULL, then ASSERT().
1426   If PublicKeySize is large enough but PublicKey is NULL, then ASSERT().
1427
1428   @param[in, out]  DhContext      Pointer to the DH context.
1429   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.
1430   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.
1431                                  On output, the size of data returned in PublicKey buffer in bytes.
1432
1433   @retval TRUE   DH public key generation succeeded.
1434   @retval FALSE  DH public key generation failed.
1435   @retval FALSE  PublicKeySize is not large enough.
1436
1437 **/
1438 BOOLEAN
1439 EFIAPI
1440 DhGenerateKey (
1441   IN OUT  VOID   *DhContext,
1442   OUT     UINT8  *PublicKey,
1443   IN OUT  UINTN  *PublicKeySize
1444   );
1445
1446 /**
1447   Computes exchanged common key.
1448
1449   Given peer's public key, this function computes the exchanged common key, based on its own
1450   context including value of prime modulus and random secret exponent.
1451
1452   If DhContext is NULL, then ASSERT().
1453   If PeerPublicKey is NULL, then ASSERT().
1454   If KeySize is NULL, then ASSERT().
1455   If KeySize is large enough but Key is NULL, then ASSERT().
1456
1457   @param[in, out]  DhContext          Pointer to the DH context.
1458   @param[in]       PeerPublicKey      Pointer to the peer's public key.
1459   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.
1460   @param[out]      Key                Pointer to the buffer to receive generated key.
1461   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.
1462                                      On output, the size of data returned in Key buffer in bytes.
1463
1464   @retval TRUE   DH exchanged key generation succeeded.
1465   @retval FALSE  DH exchanged key generation failed.
1466   @retval FALSE  KeySize is not large enough.
1467
1468 **/
1469 BOOLEAN
1470 EFIAPI
1471 DhComputeKey (
1472   IN OUT  VOID         *DhContext,
1473   IN      CONST UINT8  *PeerPublicKey,
1474   IN      UINTN        PeerPublicKeySize,
1475   OUT     UINT8        *Key,
1476   IN OUT  UINTN        *KeySize
1477   );
1478
1479 //=====================================================================================
1480 //    Pseudo-Random Generation Primitive
1481 //=====================================================================================
1482
1483 /**
1484   Sets up the seed value for the pseudorandom number generator.
1485
1486   This function sets up the seed value for the pseudorandom number generator.
1487   If Seed is not NULL, then the seed passed in is used.
1488   If Seed is NULL, then default seed is used.
1489
1490   @param[in]  Seed      Pointer to seed value.
1491                         If NULL, default seed is used.
1492   @param[in]  SeedSize  Size of seed value.
1493                         If Seed is NULL, this parameter is ignored.
1494
1495   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.
1496   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.
1497
1498 **/
1499 BOOLEAN
1500 EFIAPI
1501 RandomSeed (
1502   IN  CONST  UINT8  *Seed  OPTIONAL,
1503   IN  UINTN         SeedSize
1504   );
1505
1506 /**
1507   Generates a pseudorandom byte stream of the specified size.
1508
1509   If Output is NULL, then ASSERT().
1510
1511   @param[out]  Output  Pointer to buffer to receive random value.
1512   @param[in]   Size    Size of randome bytes to generate.
1513
1514   @retval TRUE   Pseudorandom byte stream generated successfully.
1515   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.
1516
1517 **/
1518 BOOLEAN
1519 EFIAPI
1520 RandomBytes (
1521   OUT  UINT8  *Output,
1522   IN   UINTN  Size
1523   );
1524
1525 #endif // __BASE_CRYPT_LIB_H__