NetworkPkg/IpSecDxe/IpSecCryptIo.h

   1 /** @file
   2   Definitions related to the Cryptographic Operations in IPsec.
   3
   4   Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9 #ifndef _EFI_IPSEC_CRYPTIO_H_
  10 #define _EFI_IPSEC_CRYPTIO_H_
  11
  12 #include <Protocol/IpSecConfig.h>
  13 #include <Library/DebugLib.h>
  14 #include <Library/BaseCryptLib.h>
  15 #include <Library/BaseMemoryLib.h>
  16 #include <Library/MemoryAllocationLib.h>
  17
  18 #include "IpSecImpl.h"
  19 #include "IkeCommon.h"
  20
  21 #define IPSEC_ENCRYPT_ALGORITHM_LIST_SIZE 4
  22 #define IPSEC_AUTH_ALGORITHM_LIST_SIZE    3
  23 #define IPSEC_HASH_ALGORITHM_LIST_SIZE    3
  24
  25 ///
  26 /// Authentication Algorithm Definition
  27 ///   The number value definition is aligned to IANA assignment
  28 ///
  29 #define IKE_AALG_NONE                0x00
  30 #define IKE_AALG_SHA1HMAC            0x02
  31 #define IKE_AALG_NULL                0xFB
  32
  33 ///
  34 /// Encryption Algorithm Definition
  35 ///   The number value definition is aligned to IANA assignment
  36 ///
  37 #define IKE_EALG_NONE                0x00
  38 #define IKE_EALG_3DESCBC             0x03
  39 #define IKE_EALG_NULL                0x0B
  40 #define IKE_EALG_AESCBC              0x0C
  41
  42 /**
  43   Prototype of HMAC GetContextSize.
  44
  45   Retrieves the size, in bytes, of the context buffer required.
  46
  47   @return  The size, in bytes, of the context buffer required.
  48
  49 **/
  50 typedef
  51 UINTN
  52 (EFIAPI *CRYPTO_HMAC_GETCONTEXTSIZE)(
  53   VOID
  54   );
  55
  56 /**
  57   Prototype of HMAC Operation Initiating.
  58
  59   Initialization with a new context.
  60
  61   @param[out]     Context  Input Context.
  62   @param[in]      Key      Pointer to the key for HMAC.
  63   @param[in]      KeySize  The length of the Key in bytes.
  64
  65   @retval TRUE  Initialization Successfully.
  66
  67 **/
  68 typedef
  69 BOOLEAN
  70 (EFIAPI *CRYPTO_HMAC_INIT)(
  71   OUT           VOID     *Context,
  72   IN     CONST  UINT8    *Key,
  73   IN            UINTN    KeySize
  74   );
  75
  76 /**
  77   Prototype of HMAC update.
  78   HMAC update operation. Continue an HMAC message digest operation, processing
  79   another message block, and updating the HMAC context.
  80
  81   If Context is NULL, then ASSERT().
  82   If Data is NULL, then ASSERT().
  83
  84   @param[in,out]  Context     The Specified Context.
  85   @param[in,out]  Data        The Input Data to be digested.
  86   @param[in]      DataLength  The length, in bytes, of Data.
  87
  88   @retval TRUE   Update data successfully.
  89   @retval FALSE  The Context has been finalized.
  90
  91 **/
  92 typedef
  93 BOOLEAN
  94 (EFIAPI *CRYPTO_HMAC_UPDATE)(
  95   IN OUT       VOID  *Context,
  96   IN     CONST VOID  *Data,
  97   IN           UINTN DataLength
  98   );
  99
 100 /**
 101   Prototype of HMAC finalization.
 102   Terminate a HMAC message digest operation and output the message digest.
 103
 104   If Context is NULL, then ASSERT().
 105   If HashValue is NULL, then ASSERT().
 106
 107   @param[in,out]  Context     The specified Context.
 108   @param[out]     HmacValue   Pointer to a 16-byte message digest output buffer.
 109
 110   @retval TRUE  Finalized successfully.
 111
 112 **/
 113 typedef
 114 BOOLEAN
 115 (EFIAPI *CRYPTO_HMAC_FINAL)(
 116   IN OUT  VOID   *Context,
 117      OUT  UINT8  *HmacValue
 118   );
 119
 120 /**
 121   Prototype of Block Cipher GetContextSize.
 122
 123   Retrieves the size, in bytes, of the context buffer required.
 124
 125   @return  The size, in bytes, of the context buffer required.
 126
 127 **/
 128 typedef
 129 UINTN
 130 (EFIAPI *CRYPTO_CIPHER_GETCONTEXTSIZE)(
 131   VOID
 132   );
 133
 134 /**
 135   Prototype of Block Cipher initiation.
 136   Initializes the user-supplied key as the specified context (key materials) for both
 137   encryption and decryption operations.
 138
 139   If Context is NULL, then ASSERT().
 140   If Key is NULL, then generate random key for usage.
 141
 142   @param[in,out]  Context      The specified Context.
 143   @param[in]      Key          User-supplied cipher key.
 144   @param[in]      KeyBits      Key length in bits.
 145
 146   @retval TRUE  Block Cipher Initialization was successful.
 147
 148 **/
 149 typedef
 150 BOOLEAN
 151 (EFIAPI *CRYPTO_CIPHER_INIT)(
 152   IN OUT        VOID   *Context,
 153   IN      CONST UINT8  *Key,
 154   IN            UINTN  KeyBits
 155   );
 156
 157 /**
 158   Prototype of Cipher encryption.
 159   Encrypts plaintext message with the specified cipher.
 160
 161   If Context is NULL, then ASSERT().
 162   If InData is NULL, then ASSERT().
 163   If Size of input data is not multiple of Cipher algorithm related block size,
 164   then ASSERT().
 165
 166   @param[in]      Context      The specified Context.
 167   @param[in]      InData       The input plaintext data to be encrypted.
 168   @param[in]      InputSize    The size of input data.
 169   @param[in]      Ivec         Pointer to Initial Vector data for encryption.
 170   @param[out]     OutData      The resultant encrypted ciphertext.
 171
 172   @retval TRUE  Encryption successful.
 173
 174 **/
 175 typedef
 176 BOOLEAN
 177 (EFIAPI *CRYPTO_CIPHER_ENCRYPT)(
 178   IN            VOID   *Context,
 179   IN      CONST UINT8  *InData,
 180   IN            UINTN  InputSize,
 181   IN      CONST UINT8  *Ivec,
 182       OUT       UINT8  *OutData
 183   );
 184
 185 /**
 186   Prototype of Cipher decryption.
 187   Decrypts cipher message with specified cipher.
 188
 189   If Context is NULL, then ASSERT().
 190   If InData is NULL, then ASSERT().
 191   If Size of input data is not a multiple of a certaion block size , then ASSERT().
 192
 193   @param[in]      Context      The specified Context.
 194   @param[in]      InData       The input ciphertext data to be decrypted.
 195   @param[in]      InputSize    The InData size.
 196   @param[in]      Ivec         Pointer to the Initial Vector data for decryption.
 197   @param[out]     OutData      The resultant decrypted plaintext.
 198
 199   @retval TRUE  Decryption successful.
 200
 201 **/
 202 typedef
 203 BOOLEAN
 204 (EFIAPI *CRYPTO_CIPHER_DECRYPT)(
 205   IN           VOID   *Context,
 206   IN     CONST UINT8  *InData,
 207   IN           UINTN  InputSize,
 208   IN     CONST UINT8  *Ivec,
 209      OUT       UINT8  *OutData
 210   );
 211
 212 /**
 213   Prototype of Hash ContextSize.
 214
 215   Retrieves the size, in bytes, of the context buffer required for specified hash operations.
 216
 217   @return  The size, in bytes, of the context buffer required for certain hash operations.
 218
 219 **/
 220 typedef
 221 UINTN
 222 (EFIAPI *CRYPTO_HASH_GETCONTEXTSIZE)(
 223   VOID
 224   );
 225
 226 /**
 227   Prototype of Hash Initiate.
 228
 229   Initializes user-supplied memory pointed by Context as specified hash context for
 230   subsequent use.
 231
 232   If Context is NULL, then ASSERT().
 233
 234   @param[out]  Context  Pointer to specified context being initialized.
 235
 236   @retval TRUE   context initialization succeeded.
 237   @retval FALSE  context initialization failed.
 238
 239 **/
 240 typedef
 241 BOOLEAN
 242 (EFIAPI *CRYPTO_HASH_INIT)(
 243   OUT  VOID  *Context
 244   );
 245
 246 /**
 247   Prototype of Hash Update
 248
 249   Digests the input data and updates hash context.
 250
 251   This function performs digest on a data buffer of the specified size.
 252   It can be called multiple times to compute the digest of long or discontinuous data streams.
 253   Context should be already correctly initialized by HashInit(), and should not be finalized
 254   by HashFinal(). Behavior with invalid context is undefined.
 255
 256   If Context is NULL, then ASSERT().
 257
 258   @param[in, out]  Context      Pointer to the specified context.
 259   @param[in]       Data         Pointer to the buffer containing the data to be hashed.
 260   @param[in]       DataSize     Size of Data buffer in bytes.
 261
 262   @retval TRUE   data digest succeeded.
 263   @retval FALSE  data digest failed.
 264
 265 **/
 266 typedef
 267 BOOLEAN
 268 (EFIAPI *CRYPTO_HASH_UPDATE)(
 269   IN OUT  VOID        *Context,
 270   IN      CONST VOID  *Data,
 271   IN      UINTN       DataSize
 272   );
 273
 274 /**
 275   Prototype of Hash Finalization.
 276
 277   Completes computation of the digest value.
 278
 279   This function completes hash computation and retrieves the digest value into
 280   the specified memory. After this function has been called, the context cannot
 281   be used again.
 282   context should be already correctly initialized by HashInit(), and should not be
 283   finalized by HashFinal(). Behavior with invalid context is undefined.
 284
 285   If Context is NULL, then ASSERT().
 286   If HashValue is NULL, then ASSERT().
 287
 288   @param[in, out]  Context      Pointer to the specified context.
 289   @param[out]      HashValue    Pointer to a buffer that receives the digest
 290                                 value.
 291
 292   @retval TRUE   digest computation succeeded.
 293   @retval FALSE  digest computation failed.
 294
 295 **/
 296 typedef
 297 BOOLEAN
 298 (EFIAPI *CRYPTO_HASH_FINAL)(
 299   IN OUT  VOID   *Context,
 300   OUT     UINT8  *HashValue
 301   );
 302
 303 //
 304 // The struct used to store the information and operation of Block Cipher algorithm.
 305 //
 306 typedef struct _ENCRYPT_ALGORITHM {
 307   //
 308   // The ID of the Algorithm
 309   //
 310   UINT8                     AlgorithmId;
 311   //
 312   // The Key length of the Algorithm
 313   //
 314   UINTN                     KeyLength;
 315   //
 316   // Iv Size of the Algorithm
 317   //
 318   UINTN                     IvLength;
 319   //
 320   // The Block Size of the Algorithm
 321   //
 322   UINTN                     BlockSize;
 323   //
 324   // The Function pointer of GetContextSize.
 325   //
 326   CRYPTO_CIPHER_GETCONTEXTSIZE CipherGetContextSize;
 327   //
 328   // The Function pointer of Cipher initiation.
 329   //
 330   CRYPTO_CIPHER_INIT           CipherInitiate;
 331   //
 332   // The Function pointer of Cipher Encryption.
 333   //
 334   CRYPTO_CIPHER_ENCRYPT        CipherEncrypt;
 335   //
 336   // The Function pointer of Cipher Decryption.
 337   //
 338   CRYPTO_CIPHER_DECRYPT        CipherDecrypt;
 339 } ENCRYPT_ALGORITHM;
 340
 341 //
 342 // The struct used to store the information and operation of Authentication algorithm.
 343 //
 344 typedef struct _AUTH_ALGORITHM {
 345   //
 346   // ID of the Algorithm
 347   //
 348   UINT8                    AlgorithmId;
 349   //
 350   // The Key length of the Algorithm
 351   //
 352   UINTN                    DigestLength;
 353   //
 354   // The ICV length of the Algorithm
 355   //
 356   UINTN                    IcvLength;
 357   //
 358   // The block size of the Algorithm
 359   //
 360   UINTN                    BlockSize;
 361   //
 362   // The function pointer of GetContextSize.
 363   //
 364   CRYPTO_HMAC_GETCONTEXTSIZE  HmacGetContextSize;
 365   //
 366   // The function pointer of Initiation
 367   //
 368   CRYPTO_HMAC_INIT            HmacInitiate;
 369   //
 370   // The function pointer of HMAC Update.
 371   //
 372   CRYPTO_HMAC_UPDATE          HmacUpdate;
 373   //
 374   // The fucntion pointer of HMAC Final
 375   //
 376   CRYPTO_HMAC_FINAL           HmacFinal;
 377 } AUTH_ALGORITHM;
 378
 379 //
 380 // The struct used to store the information and operation of Hash algorithm.
 381 //
 382 typedef struct _HASH_ALGORITHM {
 383   //
 384   // ID of the Algorithm
 385   //
 386   UINT8                    AlgorithmId;
 387   //
 388   // The Key length of the Algorithm
 389   //
 390   UINTN                    DigestLength;
 391   //
 392   // The ICV length of the Algorithm
 393   //
 394   UINTN                    IcvLength;
 395   //
 396   // The block size of the Algorithm
 397   //
 398   UINTN                    BlockSize;
 399   //
 400   // The function pointer of GetContextSize
 401   //
 402   CRYPTO_HASH_GETCONTEXTSIZE  HashGetContextSize;
 403   //
 404   // The function pointer of Initiation
 405   //
 406   CRYPTO_HASH_INIT            HashInitiate;
 407   //
 408   // The function pointer of Hash Update
 409   //
 410   CRYPTO_HASH_UPDATE          HashUpdate;
 411   //
 412   // The fucntion pointer of Hash Final
 413   //
 414   CRYPTO_HASH_FINAL           HashFinal;
 415 } HASH_ALGORITHM;
 416
 417 /**
 418   Get the IV size of specified encryption algorithm.
 419
 420   @param[in]  AlgorithmId          The encryption algorithm ID.
 421
 422   @return The value of IV size.
 423
 424 **/
 425 UINTN
 426 IpSecGetEncryptIvLength (
 427   IN UINT8 AlgorithmId
 428   );
 429
 430 /**
 431   Get the block size of specified encryption algorithm.
 432
 433   @param[in]  AlgorithmId          The encryption algorithm ID.
 434
 435   @return The value of block size.
 436
 437 **/
 438 UINTN
 439 IpSecGetEncryptBlockSize (
 440   IN UINT8   AlgorithmId
 441   );
 442
 443 /**
 444   Get the required key length of the specified encryption algorithm.
 445
 446   @param[in]  AlgorithmId          The encryption algorithm ID.
 447
 448   @return The value of key length.
 449
 450 **/
 451 UINTN
 452 IpSecGetEncryptKeyLength (
 453   IN UINT8   AlgorithmId
 454   );
 455
 456 /**
 457   Get the ICV size of the specified Authentication algorithm.
 458
 459   @param[in]  AlgorithmId          The Authentication algorithm ID.
 460
 461   @return The value of ICV size.
 462
 463 **/
 464 UINTN
 465 IpSecGetIcvLength (
 466   IN UINT8  AlgorithmId
 467   );
 468
 469 /**
 470   Get the HMAC digest length by the specified Algorithm ID.
 471
 472   @param[in]  AlgorithmId  The specified Algorithm ID.
 473
 474   @return The digest length of the specified Authentication Algorithm ID.
 475
 476 **/
 477 UINTN
 478 IpSecGetHmacDigestLength (
 479   IN UINT8  AlgorithmId
 480   );
 481
 482 /**
 483   Generate a random data for IV. If the IvSize is zero, not needed to create
 484   IV and return EFI_SUCCESS.
 485
 486   @param[in]  IvBuffer  The pointer of the IV buffer.
 487   @param[in]  IvSize    The IV size in bytes.
 488
 489   @retval     EFI_SUCCESS  Create random data for IV.
 490
 491 **/
 492 EFI_STATUS
 493 IpSecGenerateIv (
 494   IN UINT8                           *IvBuffer,
 495   IN UINTN                           IvSize
 496   );
 497
 498 /**
 499   Encrypt the buffer.
 500
 501   This function calls relevant encryption interface from CryptoLib according to
 502   the input algorithm ID. The InData should be multiple of block size. This function
 503   doesn't perform the padding. If it has the Ivec data, the length of it should be
 504   same with the block size. The block size is different from the different algorithm.
 505
 506   @param[in]       AlgorithmId    The Algorithm identification defined in RFC.
 507   @param[in]       Key            Pointer to the buffer containing encrypting key.
 508   @param[in]       KeyBits        The length of the key in bits.
 509   @param[in]       Ivec           Point to the buffer containing the Initialization
 510                                   Vector (IV) data.
 511   @param[in]       InData         Point to the buffer containing the data to be
 512                                   encrypted.
 513   @param[in]       InDataLength   The length of InData in Bytes.
 514   @param[out]      OutData        Point to the buffer that receives the encryption
 515                                   output.
 516
 517   @retval EFI_UNSUPPORTED       The input Algorithm is not supported.
 518   @retval EFI_OUT_OF_RESOURCE   The required resource can't be allocated.
 519   @retval EFI_SUCCESS           The operation completed successfully.
 520
 521 **/
 522 EFI_STATUS
 523 IpSecCryptoIoEncrypt (
 524   IN CONST UINT8      AlgorithmId,
 525   IN CONST UINT8      *Key,
 526   IN CONST UINTN      KeyBits,
 527   IN CONST UINT8      *Ivec, OPTIONAL
 528   IN       UINT8      *InData,
 529   IN       UINTN      InDataLength,
 530      OUT   UINT8      *OutData
 531   );
 532
 533 /**
 534   Decrypts the buffer.
 535
 536   This function calls relevant Decryption interface from CryptoLib according to
 537   the input algorithm ID. The InData should be multiple of block size. This function
 538   doesn't perform the padding. If it has the Ivec data, the length of it should be
 539   same with the block size. The block size is different from the different algorithm.
 540
 541   @param[in]       AlgorithmId    The Algorithm identification defined in RFC.
 542   @param[in]       Key            Pointer to the buffer containing encrypting key.
 543   @param[in]       KeyBits        The length of the key in bits.
 544   @param[in]       Ivec           Point to the buffer containing the Initialization
 545                                   Vector (IV) data.
 546   @param[in]       InData         Point to the buffer containing the data to be
 547                                   decrypted.
 548   @param[in]       InDataLength   The length of InData in Bytes.
 549   @param[out]      OutData        Pointer to the buffer that receives the decryption
 550                                   output.
 551
 552   @retval EFI_UNSUPPORTED       The input Algorithm is not supported.
 553   @retval EFI_OUT_OF_RESOURCE   The required resource can't be allocated.
 554   @retval EFI_SUCCESS           The operation completed successfully.
 555
 556 **/
 557 EFI_STATUS
 558 IpSecCryptoIoDecrypt (
 559   IN CONST UINT8      AlgorithmId,
 560   IN CONST UINT8      *Key,
 561   IN CONST UINTN      KeyBits,
 562   IN CONST UINT8      *Ivec, OPTIONAL
 563   IN       UINT8      *InData,
 564   IN       UINTN      InDataLength,
 565      OUT   UINT8      *OutData
 566   );
 567
 568 /**
 569   Digests the Payload with key and store the result into the OutData.
 570
 571   This function calls relevant Hmac interface from CryptoLib according to
 572   the input algorithm ID. It computes all datas from InDataFragment and output
 573   the result into the OutData buffer. If the OutDataSize is larger than the related
 574   HMAC algorithm output size, return EFI_INVALID_PARAMETER.
 575
 576   @param[in]      AlgorithmId     The authentication Identification.
 577   @param[in]      Key             Pointer of the authentication key.
 578   @param[in]      KeyLength       The length of the Key in bytes.
 579   @param[in]      InDataFragment  The list contains all data to be authenticated.
 580   @param[in]      FragmentCount   The size of the InDataFragment.
 581   @param[out]     OutData         For in, the buffer to receive the output data.
 582                                   For out, the buffer contains the authenticated data.
 583   @param[in]      OutDataSize     The size of the buffer of OutData.
 584
 585   @retval EFI_UNSUPPORTED       If the AuthAlg is not in the support list.
 586   @retval EFI_INVALID_PARAMETER The OutData buffer size is larger than algorithm digest size.
 587   @retval EFI_SUCCESS           Authenticate the payload successfully.
 588   @retval otherwise             Authentication of the payload fails.
 589
 590 **/
 591 EFI_STATUS
 592 IpSecCryptoIoHmac (
 593   IN     CONST UINT8              AlgorithmId,
 594   IN     CONST UINT8              *Key,
 595   IN           UINTN              KeyLength,
 596   IN           HASH_DATA_FRAGMENT *InDataFragment,
 597   IN           UINTN              FragmentCount,
 598      OUT       UINT8              *OutData,
 599   IN           UINTN              OutDataSize
 600   );
 601
 602 /**
 603   Digests the Payload and store the result into the OutData.
 604
 605   This function calls relevant Hash interface from CryptoLib according to
 606   the input algorithm ID. It computes all datas from InDataFragment and output
 607   the result into the OutData buffer. If the OutDataSize is larger than the related
 608   Hash algorithm output size, return EFI_INVALID_PARAMETER.
 609
 610   @param[in]      AlgorithmId     The authentication Identification.
 611   @param[in]      InDataFragment  A list contains all data to be authenticated.
 612   @param[in]      FragmentCount   The size of the InDataFragment.
 613   @param[out]     OutData         For in, the buffer to receive the output data.
 614                                   For out, the buffer contains the authenticated data.
 615   @param[in]      OutDataSize     The size of the buffer of OutData.
 616
 617   @retval EFI_UNSUPPORTED       If the AuthAlg is not in the support list.
 618   @retval EFI_SUCCESS           Authenticated the payload successfully.
 619   @retval EFI_INVALID_PARAMETER If the OutDataSize is larger than the related Hash
 620                                 algorithm could handle.
 621   @retval otherwise             Authentication of the payload failed.
 622
 623 **/
 624 EFI_STATUS
 625 IpSecCryptoIoHash (
 626   IN     CONST UINT8              AlgorithmId,
 627   IN           HASH_DATA_FRAGMENT *InDataFragment,
 628   IN           UINTN              FragmentCount,
 629      OUT       UINT8              *OutData,
 630   IN           UINTN              OutDataSize
 631   );
 632
 633 /**
 634   Generates the Diffie-Hellman public key.
 635
 636   This function first initiate a DHContext, then call the DhSetParameter() to set
 637   the prime and primelength, at end call the DhGenerateKey() to generates random
 638   secret exponent, and computes the public key. The output returned via parameter
 639   PublicKey and PublicKeySize. DH context is updated accordingly. If the PublicKey
 640   buffer is too small to hold the public key, EFI_INVALID_PARAMETER is returned
 641   and PublicKeySize is set to the required buffer size to obtain the public key.
 642
 643   @param[in, out] DhContext       Pointer to the DH context.
 644   @param[in]      Generator       Value of generator.
 645   @param[in]      PrimeLength     Length in bits of prime to be generated.
 646   @param[in]      Prime           Pointer to the buffer to receive the generated
 647                                   prime number.
 648   @param[out]     PublicKey       Pointer to the buffer to receive generated public key.
 649   @param[in, out] PublicKeySize   For in, the size of PublicKey buffer in bytes.
 650                                   For out, the size of data returned in PublicKey
 651                                   buffer in bytes.
 652
 653   @retval EFI_SUCCESS             The operation performs successfully.
 654   @retval Otherwise               The operation is failed.
 655
 656 **/
 657 EFI_STATUS
 658 IpSecCryptoIoDhGetPublicKey (
 659   IN OUT   UINT8  **DhContext,
 660   IN       UINTN  Generator,
 661   IN       UINTN  PrimeLength,
 662   IN CONST UINT8  *Prime,
 663      OUT   UINT8  *PublicKey,
 664   IN OUT   UINTN  *PublicKeySize
 665   );
 666
 667 /**
 668   Generates exchanged common key.
 669
 670   Given peer's public key, this function computes the exchanged common key, based
 671   on its own context including value of prime modulus and random secret exponent.
 672
 673   @param[in, out] DhContext         Pointer to the DH context.
 674   @param[in]      PeerPublicKey     Pointer to the peer's Public Key.
 675   @param[in]      PeerPublicKeySize Size of peer's public key in bytes.
 676   @param[out]     Key               Pointer to the buffer to receive generated key.
 677   @param[in, out] KeySize           For in, the size of Key buffer in bytes.
 678                                     For out, the size of data returned in Key
 679                                     buffer in bytes.
 680
 681   @retval EFI_SUCCESS              The operation performs successfully.
 682   @retval Otherwise                The operation is failed.
 683
 684 **/
 685 EFI_STATUS
 686 IpSecCryptoIoDhComputeKey (
 687   IN   OUT   UINT8  *DhContext,
 688   IN   CONST UINT8  *PeerPublicKey,
 689   IN         UINTN  PeerPublicKeySize,
 690        OUT   UINT8  *Key,
 691   IN   OUT   UINTN  *KeySize
 692   );
 693
 694 /**
 695   Releases the DH context. If DhContext is NULL, return EFI_INVALID_PARAMETER.
 696
 697   @param[in, out]     DhContext         Pointer to the DH context to be freed.
 698
 699   @retval EFI_SUCCESS              The operation performs successfully.
 700   @retval EFI_INVALID_PARAMETER    The DhContext is NULL.
 701
 702 **/
 703 EFI_STATUS
 704 IpSecCryptoIoFreeDh (
 705   IN   OUT   UINT8  **DhContext
 706   );
 707
 708 /**
 709   Generates random numbers of specified size.
 710
 711   If the Random Generator wasn't initiated, initiate it first, then call RandomBytes.
 712
 713   @param[out]  OutBuffer        Pointer to buffer to receive random value.
 714   @param[in]   Bytes            Size of random bytes to generate.
 715
 716   @retval EFI_SUCCESS              The operation performs successfully.
 717   @retval Otherwise                The operation is failed.
 718
 719 **/
 720 EFI_STATUS
 721 IpSecCryptoIoGenerateRandomBytes (
 722   OUT UINT8*    OutBuffer,
 723   IN  UINTN     Bytes
 724   );
 725
 726 /**
 727   Authenticate data with the certificate.
 728
 729   @param[in]      InData          Pointer to the Data to be signed.
 730   @param[in]      InDataSize      InData size in bytes.
 731   @param[in]      PrivateKey      Pointer to the  private key.
 732   @param[in]      PrivateKeySize  The size of Private Key in bytes.
 733   @param[in]      KeyPassWord     Pointer to the password for retrieving private key.
 734   @param[in]      KeyPwdSize      The size of Key Password in bytes.
 735   @param[out]     OutData         The pointer to the signed data.
 736   @param[in, out] OutDataSize     Pointer to contain the size of out data.
 737
 738 **/
 739 VOID
 740 IpSecCryptoIoAuthDataWithCertificate (
 741   IN     UINT8   *InData,
 742   IN     UINTN   InDataSize,
 743   IN     UINT8   *PrivateKey,
 744   IN     UINTN   PrivateKeySize,
 745   IN     UINT8   *KeyPassWord,
 746   IN     UINTN   KeyPwdSize,
 747      OUT UINT8   **OutData,
 748   IN OUT UINTN   *OutDataSize
 749   );
 750
 751 /**
 752   Verify the singed data with the public key which is contained in a certificate.
 753
 754   @param[in]     InCert          Pointer to the Certificate which contains the
 755                                  public key.
 756   @param[in]     CertLen         The size of Certificate in bytes.
 757   @param[in]     InCa            Pointer to the CA certificate
 758   @param[in]     CaLen           The size of CA certificate in bytes.
 759   @param[in]     InData          Pointer to octet message hash to be checked.
 760   @param[in]     InDataSize      Size of the message hash in bytes.
 761   @param[in]     Singnature      The pointer to the RSA PKCS1-V1_5 signature to be verified.
 762   @param[in]     SigSize         Size of signature in bytes.
 763
 764   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.
 765   @retval  FALSE  Invalid signature or invalid RSA context.
 766
 767 **/
 768 BOOLEAN
 769 IpSecCryptoIoVerifySignDataByCertificate (
 770   IN     UINT8   *InCert,
 771   IN     UINTN   CertLen,
 772   IN     UINT8   *InCa,
 773   IN     UINTN   CaLen,
 774   IN     UINT8   *InData,
 775   IN     UINTN   InDataSize,
 776   IN     UINT8   *Singnature,
 777   IN     UINTN   SigSize
 778   );
 779
 780 /**
 781   Retrieves the RSA Public Key from one X509 certificate (DER format only).
 782
 783   @param[in]     InCert            Pointer to the certificate.
 784   @param[in]     CertLen           The size of the certificate in bytes.
 785   @param[out]    PublicKey         Pointer to the retrieved public key.
 786   @param[out]    PublicKeyLen      Size of Public Key in bytes.
 787
 788   @retval  EFI_SUCCESS            Successfully get the public Key.
 789   @retval  EFI_INVALID_PARAMETER  The CA certificate is malformed.
 790
 791 **/
 792 EFI_STATUS
 793 IpSecCryptoIoGetPublicKeyFromCert (
 794   IN     UINT8   *InCert,
 795   IN     UINTN   CertLen,
 796   OUT    UINT8   **PublicKey,
 797   OUT    UINTN   *PublicKeyLen
 798   );
 799
 800 /**
 801   Retrieves the subject name from one X509 certificate (DER format only).
 802
 803   @param[in]     InCert            Pointer to the X509 certificate.
 804   @param[in]     CertSize          The size of the X509 certificate in bytes.
 805   @param[out]    CertSubject       Pointer to the retrieved certificate subject.
 806   @param[out]    SubjectSize       The size of Certificate Subject in bytes.
 807
 808   @retval  EFI_SUCCESS            Retrieved the certificate subject successfully.
 809   @retval  EFI_INVALID_PARAMETER  The certificate is malformed.
 810
 811 **/
 812 EFI_STATUS
 813 IpSecCryptoIoGetSubjectFromCert (
 814   IN     UINT8   *InCert,
 815   IN     UINTN   CertSize,
 816   OUT    UINT8   **CertSubject,
 817   OUT    UINTN   *SubjectSize
 818   );
 819
 820 #endif
 821