CryptoPkg: Change OPTIONAL keyword usage style

[mirror_edk2.git] / CryptoPkg / Private / Protocol / Crypto.h

diff --git a/CryptoPkg/Private/Protocol/Crypto.h b/CryptoPkg/Private/Protocol/Crypto.h
index f36c5c1aff4dbe8a1ba84c312e03bd23bcdd82bb..e38ecbb3b117e80749b790192a05168d41d795d7 100644 (file)
--- a/CryptoPkg/Private/Protocol/Crypto.h
+++ b/CryptoPkg/Private/Protocol/Crypto.h
@@ -2,6 +2,7 @@
   This Protocol provides Crypto services to DXE modules\r
 \r
   Copyright (C) Microsoft Corporation. All rights reserved.\r
   This Protocol provides Crypto services to DXE modules\r
 \r
   Copyright (C) Microsoft Corporation. All rights reserved.\r

+  Copyright (c) 2020 - 2021, Intel Corporation. All rights reserved.<BR>\r

   SPDX-License-Identifier: BSD-2-Clause-Patent\r
 \r
 **/\r
   SPDX-License-Identifier: BSD-2-Clause-Patent\r
 \r
 **/\r


@@ -20,7 +21,7 @@
 /// the EDK II Crypto Protocol is extended, this version define must be\r
 /// increased.\r
 ///\r
 /// the EDK II Crypto Protocol is extended, this version define must be\r
 /// increased.\r
 ///\r

-#define EDKII_CRYPTO_VERSION 6\r
+#define EDKII_CRYPTO_VERSION 7\r

 \r
 ///\r
 /// EDK II Crypto Protocol forward declaration\r
 \r
 ///\r
 /// EDK II Crypto Protocol forward declaration\r


@@ -43,273 +44,95 @@ UINTN
 //    MAC (Message Authentication Code) Primitive\r
 //=====================================================================================\r
 /**\r
 //    MAC (Message Authentication Code) Primitive\r
 //=====================================================================================\r
 /**\r

-  Allocates and initializes one HMAC_CTX context for subsequent HMAC-MD5 use.\r
-\r
-  If this interface is not supported, then return NULL.\r
-\r
-  @return  Pointer to the HMAC_CTX context that has been initialized.\r
-           If the allocations fails, HmacMd5New() returns NULL.\r
-  @retval  NULL  This interface is not supported.\r
+  HMAC MD5 is deprecated and unsupported any longer.\r
+  Keep the function field for binary compability.\r

 \r
 **/\r
 typedef\r
 VOID*\r
 \r
 **/\r
 typedef\r
 VOID*\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_NEW) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_NEW) (\r

   VOID\r
   );\r
 \r
   VOID\r
   );\r
 \r

-/**\r
-  Release the specified HMAC_CTX context.\r
-\r
-  If this interface is not supported, then do nothing.\r
-\r
-  @param[in]  HmacMd5Ctx  Pointer to the HMAC_CTX context to be released.\r
-\r
-**/\r

 typedef\r
 VOID\r
 typedef\r
 VOID\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_FREE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_FREE) (\r

   IN  VOID  *HmacMd5Ctx\r
   );\r
 \r
   IN  VOID  *HmacMd5Ctx\r
   );\r
 \r

-/**\r
-  Set user-supplied key for subsequent use. It must be done before any\r
-  calling to HmacMd5Update().\r
-\r
-  If HmacMd5Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context.\r
-  @param[in]   Key             Pointer to the user-supplied key.\r
-  @param[in]   KeySize         Key size in bytes.\r
-\r
-  @retval TRUE   HMAC-MD5 context initialization succeeded.\r
-  @retval FALSE  HMAC-MD5 context initialization failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_SET_KEY) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_SET_KEY) (\r

   OUT  VOID         *HmacMd5Context,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeySize\r
   );\r
 \r
   OUT  VOID         *HmacMd5Context,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeySize\r
   );\r
 \r

-/**\r
-  Makes a copy of an existing HMAC-MD5 context.\r
-\r
-  If HmacMd5Context is NULL, then return FALSE.\r
-  If NewHmacMd5Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.\r
-  @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.\r
-\r
-  @retval TRUE   HMAC-MD5 context copy succeeded.\r
-  @retval FALSE  HMAC-MD5 context copy failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_DUPLICATE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_DUPLICATE) (\r

   IN   CONST VOID  *HmacMd5Context,\r
   OUT  VOID        *NewHmacMd5Context\r
   );\r
 \r
   IN   CONST VOID  *HmacMd5Context,\r
   OUT  VOID        *NewHmacMd5Context\r
   );\r
 \r

-/**\r
-  Digests the input data and updates HMAC-MD5 context.\r
-\r
-  This function performs HMAC-MD5 digest on a data buffer of the specified size.\r
-  It can be called multiple times to compute the digest of long or discontinuous data streams.\r
-  HMAC-MD5 context should be initialized by HmacMd5New(), and should not be finalized by\r
-  HmacMd5Final(). Behavior with invalid context is undefined.\r
-\r
-  If HmacMd5Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
-  @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
-  @param[in]       DataSize        Size of Data buffer in bytes.\r
-\r
-  @retval TRUE   HMAC-MD5 data digest succeeded.\r
-  @retval FALSE  HMAC-MD5 data digest failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_UPDATE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_UPDATE) (\r

   IN OUT  VOID        *HmacMd5Context,\r
   IN      CONST VOID  *Data,\r
   IN      UINTN       DataSize\r
   );\r
 \r
   IN OUT  VOID        *HmacMd5Context,\r
   IN      CONST VOID  *Data,\r
   IN      UINTN       DataSize\r
   );\r
 \r

-\r
-/**\r
-  Completes computation of the HMAC-MD5 digest value.\r
-\r
-  This function completes HMAC-MD5 hash computation and retrieves the digest value into\r
-  the specified memory. After this function has been called, the HMAC-MD5 context cannot\r
-  be used again.\r
-  HMAC-MD5 context should be initialized by HmacMd5New(), and should not be finalized by\r
-  HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.\r
-\r
-  If HmacMd5Context is NULL, then return FALSE.\r
-  If HmacValue is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
-  @param[out]      HmacValue       Pointer to a buffer that receives the HMAC-MD5 digest\r
-                                   value (16 bytes).\r
-\r
-  @retval TRUE   HMAC-MD5 digest computation succeeded.\r
-  @retval FALSE  HMAC-MD5 digest computation failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_MD5_FINAL) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_MD5_FINAL) (\r

   IN OUT  VOID   *HmacMd5Context,\r
   OUT     UINT8  *HmacValue\r
   );\r
 \r
   IN OUT  VOID   *HmacMd5Context,\r
   OUT     UINT8  *HmacValue\r
   );\r
 \r

-\r

 /**\r
 /**\r

-  Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA1 use.\r
-\r
-  If this interface is not supported, then return NULL.\r
-\r
-  @return  Pointer to the HMAC_CTX context that has been initialized.\r
-           If the allocations fails, HmacSha1New() returns NULL.\r
-  @return  NULL   This interface is not supported.\r
+  HMAC SHA1 is deprecated and unsupported any longer.\r
+  Keep the function field for binary compability.\r

 \r
 **/\r
 typedef\r
 VOID*\r
 \r
 **/\r
 typedef\r
 VOID*\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_NEW) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_NEW) (\r

   VOID\r
   );\r
 \r
   VOID\r
   );\r
 \r

-/**\r
-  Release the specified HMAC_CTX context.\r
-\r
-  If this interface is not supported, then do nothing.\r
-\r
-  @param[in]  HmacSha1Ctx  Pointer to the HMAC_CTX context to be released.\r
-\r
-**/\r

 typedef\r
 VOID\r
 typedef\r
 VOID\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_FREE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_FREE) (\r

   IN  VOID  *HmacSha1Ctx\r
   );\r
 \r
   IN  VOID  *HmacSha1Ctx\r
   );\r
 \r

-\r
-/**\r
-  Set user-supplied key for subsequent use. It must be done before any\r
-  calling to HmacSha1Update().\r
-\r
-  If HmacSha1Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context.\r
-  @param[in]   Key              Pointer to the user-supplied key.\r
-  @param[in]   KeySize          Key size in bytes.\r
-\r
-  @retval TRUE   The Key is set successfully.\r
-  @retval FALSE  The Key is set unsuccessfully.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_SET_KEY) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_SET_KEY) (\r

   OUT  VOID         *HmacSha1Context,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeySize\r
   );\r
 \r
   OUT  VOID         *HmacSha1Context,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeySize\r
   );\r
 \r

-\r
-/**\r
-  Makes a copy of an existing HMAC-SHA1 context.\r
-\r
-  If HmacSha1Context is NULL, then return FALSE.\r
-  If NewHmacSha1Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.\r
-  @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.\r
-\r
-  @retval TRUE   HMAC-SHA1 context copy succeeded.\r
-  @retval FALSE  HMAC-SHA1 context copy failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_DUPLICATE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_DUPLICATE) (\r

   IN   CONST VOID  *HmacSha1Context,\r
   OUT  VOID        *NewHmacSha1Context\r
   );\r
 \r
   IN   CONST VOID  *HmacSha1Context,\r
   OUT  VOID        *NewHmacSha1Context\r
   );\r
 \r

-\r
-/**\r
-  Digests the input data and updates HMAC-SHA1 context.\r
-\r
-  This function performs HMAC-SHA1 digest on a data buffer of the specified size.\r
-  It can be called multiple times to compute the digest of long or discontinuous data streams.\r
-  HMAC-SHA1 context should be initialized by HmacSha1New(), and should not be finalized by\r
-  HmacSha1Final(). Behavior with invalid context is undefined.\r
-\r
-  If HmacSha1Context is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.\r
-  @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
-  @param[in]       DataSize        Size of Data buffer in bytes.\r
-\r
-  @retval TRUE   HMAC-SHA1 data digest succeeded.\r
-  @retval FALSE  HMAC-SHA1 data digest failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_UPDATE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_UPDATE) (\r

   IN OUT  VOID        *HmacSha1Context,\r
   IN      CONST VOID  *Data,\r
   IN      UINTN       DataSize\r
   );\r
 \r
   IN OUT  VOID        *HmacSha1Context,\r
   IN      CONST VOID  *Data,\r
   IN      UINTN       DataSize\r
   );\r
 \r

-\r
-/**\r
-  Completes computation of the HMAC-SHA1 digest value.\r
-\r
-  This function completes HMAC-SHA1 hash computation and retrieves the digest value into\r
-  the specified memory. After this function has been called, the HMAC-SHA1 context cannot\r
-  be used again.\r
-  HMAC-SHA1 context should be initialized by HmacSha1New(), and should not be finalized\r
-  by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.\r
-\r
-  If HmacSha1Context is NULL, then return FALSE.\r
-  If HmacValue is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.\r
-  @param[out]      HmacValue        Pointer to a buffer that receives the HMAC-SHA1 digest\r
-                                    value (20 bytes).\r
-\r
-  @retval TRUE   HMAC-SHA1 digest computation succeeded.\r
-  @retval FALSE  HMAC-SHA1 digest computation failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_HMAC_SHA1_FINAL) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_FINAL) (\r

   IN OUT  VOID   *HmacSha1Context,\r
   OUT     UINT8  *HmacValue\r
   );\r
   IN OUT  VOID   *HmacSha1Context,\r
   OUT     UINT8  *HmacValue\r
   );\r


@@ -1283,32 +1106,6 @@ BOOLEAN
   IN  UINTN                         SigSize\r
   );\r
 \r
   IN  UINTN                         SigSize\r
   );\r
 \r

-/**\r
-  Retrieve the RSA Public Key from one DER-encoded X509 certificate.\r
-\r
-  If Cert is NULL, then return FALSE.\r
-  If RsaContext is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]  Cert         Pointer to the DER-encoded X509 certificate.\r
-  @param[in]  CertSize     Size of the X509 certificate in bytes.\r
-  @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved\r
-                           RSA public key component. Use RsaFree() function to free the\r
-                           resource.\r
-\r
-  @retval  TRUE   RSA Public Key was retrieved successfully.\r
-  @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.\r
-  @retval  FALSE  This interface is not supported.\r
-\r
-**/\r
-typedef\r
-BOOLEAN\r
-(EFIAPI *EDKII_CRYPTO_RSA_GET_PUBLIC_KEY_FROM_X509) (\r
-  IN   CONST UINT8  *Cert,\r
-  IN   UINTN        CertSize,\r
-  OUT  VOID         **RsaContext\r
-  );\r
-\r

 /**\r
   Allocates and initializes one RSA context for subsequent use.\r
 \r
 /**\r
   Allocates and initializes one RSA context for subsequent use.\r
 \r


@@ -2194,7 +1991,7 @@ EFI_STATUS
 (EFIAPI *EDKII_CRYPTO_X509_GET_COMMON_NAME) (\r
   IN      CONST UINT8  *Cert,\r
   IN      UINTN        CertSize,\r
 (EFIAPI *EDKII_CRYPTO_X509_GET_COMMON_NAME) (\r
   IN      CONST UINT8  *Cert,\r
   IN      UINTN        CertSize,\r

-  OUT     CHAR8        *CommonName,  OPTIONAL\r
+  OUT     CHAR8        *CommonName   OPTIONAL,\r

   IN OUT  UINTN        *CommonNameSize\r
   );\r
 \r
   IN OUT  UINTN        *CommonNameSize\r
   );\r
 \r


@@ -2229,7 +2026,7 @@ EFI_STATUS
 (EFIAPI *EDKII_CRYPTO_X509_GET_ORGANIZATION_NAME) (\r
   IN      CONST UINT8  *Cert,\r
   IN      UINTN        CertSize,\r
 (EFIAPI *EDKII_CRYPTO_X509_GET_ORGANIZATION_NAME) (\r
   IN      CONST UINT8  *Cert,\r
   IN      UINTN        CertSize,\r

-  OUT     CHAR8        *NameBuffer,  OPTIONAL\r
+  OUT     CHAR8        *NameBuffer   OPTIONAL,\r

   IN OUT  UINTN        *NameBufferSize\r
   );\r
 \r
   IN OUT  UINTN        *NameBufferSize\r
   );\r
 \r


@@ -2396,155 +2193,45 @@ BOOLEAN
 //=====================================================================================\r
 \r
 /**\r
 //=====================================================================================\r
 \r
 /**\r

-  Retrieves the size, in bytes, of the context buffer required for TDES operations.\r
-\r
-  If this interface is not supported, then return zero.\r
-\r
-  @return  The size, in bytes, of the context buffer required for TDES operations.\r
-  @retval  0   This interface is not supported.\r
+  TDES is deprecated and unsupported any longer.\r
+  Keep the function field for binary compability.\r

 \r
 **/\r
 typedef\r
 UINTN\r
 \r
 **/\r
 typedef\r
 UINTN\r

-(EFIAPI *EDKII_CRYPTO_TDES_GET_CONTEXT_SIZE) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_GET_CONTEXT_SIZE) (\r

   VOID\r
   );\r
 \r
   VOID\r
   );\r
 \r

-/**\r
-  Initializes user-supplied memory as TDES context for subsequent use.\r
-\r
-  This function initializes user-supplied memory pointed by TdesContext as TDES context.\r
-  In addition, it sets up all TDES key materials for subsequent encryption and decryption\r
-  operations.\r
-  There are 3 key options as follows:\r
-  KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)\r
-  KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)\r
-  KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)\r
-\r
-  If TdesContext is NULL, then return FALSE.\r
-  If Key is NULL, then return FALSE.\r
-  If KeyLength is not valid, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[out]  TdesContext  Pointer to TDES context being initialized.\r
-  @param[in]   Key          Pointer to the user-supplied TDES key.\r
-  @param[in]   KeyLength    Length of TDES key in bits.\r
-\r
-  @retval TRUE   TDES context initialization succeeded.\r
-  @retval FALSE  TDES context initialization failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_TDES_INIT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_INIT) (\r

   OUT  VOID         *TdesContext,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeyLength\r
   );\r
 \r
   OUT  VOID         *TdesContext,\r
   IN   CONST UINT8  *Key,\r
   IN   UINTN        KeyLength\r
   );\r
 \r

-/**\r
-  Performs TDES encryption on a data buffer of the specified size in ECB mode.\r
-\r
-  This function performs TDES encryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in ECB mode.\r
-  InputSize must be multiple of block size (8 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
-  invalid TDES context is undefined.\r
-\r
-  If TdesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   TdesContext  Pointer to the TDES context.\r
-  @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
-  @param[in]   InputSize    Size of the Input buffer in bytes.\r
-  @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
-\r
-  @retval TRUE   TDES encryption succeeded.\r
-  @retval FALSE  TDES encryption failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_TDES_ECB_ENCRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_ECB_ENCRYPT) (\r

   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r
   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r

-/**\r
-  Performs TDES decryption on a data buffer of the specified size in ECB mode.\r
-\r
-  This function performs TDES decryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in ECB mode.\r
-  InputSize must be multiple of block size (8 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
-  invalid TDES context is undefined.\r
-\r
-  If TdesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   TdesContext  Pointer to the TDES context.\r
-  @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
-  @param[in]   InputSize    Size of the Input buffer in bytes.\r
-  @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.\r
-\r
-  @retval TRUE   TDES decryption succeeded.\r
-  @retval FALSE  TDES decryption failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_TDES_ECB_DECRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_ECB_DECRYPT) (\r

   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r
   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r

-/**\r
-  Performs TDES encryption on a data buffer of the specified size in CBC mode.\r
-\r
-  This function performs TDES encryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in CBC mode.\r
-  InputSize must be multiple of block size (8 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  Initialization vector should be one block size (8 bytes).\r
-  TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
-  invalid TDES context is undefined.\r
-\r
-  If TdesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
-  If Ivec is NULL, then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   TdesContext  Pointer to the TDES context.\r
-  @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
-  @param[in]   InputSize    Size of the Input buffer in bytes.\r
-  @param[in]   Ivec         Pointer to initialization vector.\r
-  @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
-\r
-  @retval TRUE   TDES encryption succeeded.\r
-  @retval FALSE  TDES encryption failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_TDES_CBC_ENCRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_CBC_ENCRYPT) (\r

   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r


@@ -2552,38 +2239,9 @@ BOOLEAN
   OUT  UINT8        *Output\r
   );\r
 \r
   OUT  UINT8        *Output\r
   );\r
 \r

-/**\r
-  Performs TDES decryption on a data buffer of the specified size in CBC mode.\r
-\r
-  This function performs TDES decryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in CBC mode.\r
-  InputSize must be multiple of block size (8 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  Initialization vector should be one block size (8 bytes).\r
-  TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
-  invalid TDES context is undefined.\r
-\r
-  If TdesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
-  If Ivec is NULL, then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   TdesContext  Pointer to the TDES context.\r
-  @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
-  @param[in]   InputSize    Size of the Input buffer in bytes.\r
-  @param[in]   Ivec         Pointer to initialization vector.\r
-  @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
-\r
-  @retval TRUE   TDES decryption succeeded.\r
-  @retval FALSE  TDES decryption failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_TDES_CBC_DECRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_TDES_CBC_DECRYPT) (\r

   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   IN   VOID         *TdesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r


@@ -2637,69 +2295,22 @@ BOOLEAN
   );\r
 \r
 /**\r
   );\r
 \r
 /**\r

-  Performs AES encryption on a data buffer of the specified size in ECB mode.\r
-\r
-  This function performs AES encryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in ECB mode.\r
-  InputSize must be multiple of block size (16 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  AesContext should be already correctly initialized by AesInit(). Behavior with\r
-  invalid AES context is undefined.\r
-\r
-  If AesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   AesContext  Pointer to the AES context.\r
-  @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
-  @param[in]   InputSize   Size of the Input buffer in bytes.\r
-  @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
-\r
-  @retval TRUE   AES encryption succeeded.\r
-  @retval FALSE  AES encryption failed.\r
-  @retval FALSE  This interface is not supported.\r
+  AES ECB Mode is deprecated and unsupported any longer.\r
+  Keep the function field for binary compability.\r

 \r
 **/\r
 typedef\r
 BOOLEAN\r
 \r
 **/\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_AES_ECB_ENCRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_AES_ECB_ENCRYPT) (\r

   IN   VOID         *AesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r
   IN   VOID         *AesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   OUT  UINT8        *Output\r
   );\r
 \r

-/**\r
-  Performs AES decryption on a data buffer of the specified size in ECB mode.\r
-\r
-  This function performs AES decryption on data buffer pointed by Input, of specified\r
-  size of InputSize, in ECB mode.\r
-  InputSize must be multiple of block size (16 bytes). This function does not perform\r
-  padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
-  AesContext should be already correctly initialized by AesInit(). Behavior with\r
-  invalid AES context is undefined.\r
-\r
-  If AesContext is NULL, then return FALSE.\r
-  If Input is NULL, then return FALSE.\r
-  If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
-  If Output is NULL, then return FALSE.\r
-  If this interface is not supported, then return FALSE.\r
-\r
-  @param[in]   AesContext  Pointer to the AES context.\r
-  @param[in]   Input       Pointer to the buffer containing the data to be decrypted.\r
-  @param[in]   InputSize   Size of the Input buffer in bytes.\r
-  @param[out]  Output      Pointer to a buffer that receives the AES decryption output.\r
-\r
-  @retval TRUE   AES decryption succeeded.\r
-  @retval FALSE  AES decryption failed.\r
-  @retval FALSE  This interface is not supported.\r
-\r
-**/\r

 typedef\r
 BOOLEAN\r
 typedef\r
 BOOLEAN\r

-(EFIAPI *EDKII_CRYPTO_AES_ECB_DECRYPT) (\r
+(EFIAPI *DEPRECATED_EDKII_CRYPTO_AES_ECB_DECRYPT) (\r

   IN   VOID         *AesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r
   IN   VOID         *AesContext,\r
   IN   CONST UINT8  *Input,\r
   IN   UINTN        InputSize,\r


@@ -3124,9 +2735,9 @@ typedef
 EFI_STATUS\r
 (EFIAPI* EDKII_CRYPTO_TLS_DO_HANDSHAKE)(\r
   IN     VOID                     *Tls,\r
 EFI_STATUS\r
 (EFIAPI* EDKII_CRYPTO_TLS_DO_HANDSHAKE)(\r
   IN     VOID                     *Tls,\r

-  IN     UINT8                    *BufferIn, OPTIONAL\r
-  IN     UINTN                    BufferInSize, OPTIONAL\r
-     OUT UINT8                    *BufferOut, OPTIONAL\r
+  IN     UINT8                    *BufferIn  OPTIONAL,\r
+  IN     UINTN                    BufferInSize  OPTIONAL,\r
+     OUT UINT8                    *BufferOut  OPTIONAL,\r

   IN OUT UINTN                    *BufferOutSize\r
   );\r
 \r
   IN OUT UINTN                    *BufferOutSize\r
   );\r
 \r


@@ -3159,9 +2770,9 @@ typedef
 EFI_STATUS\r
 (EFIAPI* EDKII_CRYPTO_TLS_HANDLE_ALERT)(\r
   IN     VOID                     *Tls,\r
 EFI_STATUS\r
 (EFIAPI* EDKII_CRYPTO_TLS_HANDLE_ALERT)(\r
   IN     VOID                     *Tls,\r

-  IN     UINT8                    *BufferIn, OPTIONAL\r
-  IN     UINTN                    BufferInSize, OPTIONAL\r
-     OUT UINT8                    *BufferOut, OPTIONAL\r
+  IN     UINT8                    *BufferIn  OPTIONAL,\r
+  IN     UINTN                    BufferInSize  OPTIONAL,\r
+     OUT UINT8                    *BufferOut  OPTIONAL,\r

   IN OUT UINTN                    *BufferOutSize\r
   );\r
 \r
   IN OUT UINTN                    *BufferOutSize\r
   );\r
 \r


@@ -3797,6 +3408,81 @@ EFI_STATUS
   IN OUT UINTN                    *DataSize\r
   );\r
 \r
   IN OUT UINTN                    *DataSize\r
   );\r
 \r

+/**\r
+  Carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme.\r
+\r
+  This function carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme defined in\r
+  RFC 8017.\r
+  Mask generation function is the same as the message digest algorithm.\r
+  If the Signature buffer is too small to hold the contents of signature, FALSE\r
+  is returned and SigSize is set to the required buffer size to obtain the signature.\r
+\r
+  If RsaContext is NULL, then return FALSE.\r
+  If Message is NULL, then return FALSE.\r
+  If MsgSize is zero or > INT_MAX, then return FALSE.\r
+  If DigestLen is NOT 32, 48 or 64, return FALSE.\r
+  If SaltLen is not equal to DigestLen, then return FALSE.\r
+  If SigSize is large enough but Signature is NULL, then return FALSE.\r
+  If this interface is not supported, then return FALSE.\r
+\r
+  @param[in]      RsaContext   Pointer to RSA context for signature generation.\r
+  @param[in]      Message      Pointer to octet message to be signed.\r
+  @param[in]      MsgSize      Size of the message in bytes.\r
+  @param[in]      DigestLen    Length of the digest in bytes to be used for RSA signature operation.\r
+  @param[in]      SaltLen      Length of the salt in bytes to be used for PSS encoding.\r
+  @param[out]     Signature    Pointer to buffer to receive RSA PSS signature.\r
+  @param[in, out] SigSize      On input, the size of Signature buffer in bytes.\r
+                               On output, the size of data returned in Signature buffer in bytes.\r
+\r
+  @retval  TRUE   Signature successfully generated in RSASSA-PSS.\r
+  @retval  FALSE  Signature generation failed.\r
+  @retval  FALSE  SigSize is too small.\r
+  @retval  FALSE  This interface is not supported.\r
+\r
+**/\r
+typedef\r
+BOOLEAN\r
+(EFIAPI* EDKII_CRYPTO_RSA_PSS_SIGN)(\r
+  IN      VOID         *RsaContext,\r
+  IN      CONST UINT8  *Message,\r
+  IN      UINTN        MsgSize,\r
+  IN      UINT16       DigestLen,\r
+  IN      UINT16       SaltLen,\r
+  OUT     UINT8        *Signature,\r
+  IN OUT  UINTN        *SigSize\r
+  );\r
+\r
+/**\r
+  Verifies the RSA signature with RSASSA-PSS signature scheme defined in RFC 8017.\r
+  Implementation determines salt length automatically from the signature encoding.\r
+  Mask generation function is the same as the message digest algorithm.\r
+  Salt length should be equal to digest length.\r
+\r
+  @param[in]  RsaContext      Pointer to RSA context for signature verification.\r
+  @param[in]  Message         Pointer to octet message to be verified.\r
+  @param[in]  MsgSize         Size of the message in bytes.\r
+  @param[in]  Signature       Pointer to RSASSA-PSS signature to be verified.\r
+  @param[in]  SigSize         Size of signature in bytes.\r
+  @param[in]  DigestLen       Length of digest for RSA operation.\r
+  @param[in]  SaltLen         Salt length for PSS encoding.\r
+\r
+  @retval  TRUE   Valid signature encoded in RSASSA-PSS.\r
+  @retval  FALSE  Invalid signature or invalid RSA context.\r
+\r
+**/\r
+typedef\r
+BOOLEAN\r
+(EFIAPI* EDKII_CRYPTO_RSA_PSS_VERIFY)(\r
+  IN  VOID         *RsaContext,\r
+  IN  CONST UINT8  *Message,\r
+  IN  UINTN        MsgSize,\r
+  IN  CONST UINT8  *Signature,\r
+  IN  UINTN        SigSize,\r
+  IN  UINT16       DigestLen,\r
+  IN  UINT16       SaltLen\r
+  );\r
+\r
+\r

 \r
 ///\r
 /// EDK II Crypto Protocol\r
 \r
 ///\r
 /// EDK II Crypto Protocol\r


@@ -3804,20 +3490,20 @@ EFI_STATUS
 struct _EDKII_CRYPTO_PROTOCOL {\r
   /// Version\r
   EDKII_CRYPTO_GET_VERSION                        GetVersion;\r
 struct _EDKII_CRYPTO_PROTOCOL {\r
   /// Version\r
   EDKII_CRYPTO_GET_VERSION                        GetVersion;\r

-  /// HMAC MD5\r
-  EDKII_CRYPTO_HMAC_MD5_NEW                       HmacMd5New;\r
-  EDKII_CRYPTO_HMAC_MD5_FREE                      HmacMd5Free;\r
-  EDKII_CRYPTO_HMAC_MD5_SET_KEY                   HmacMd5SetKey;\r
-  EDKII_CRYPTO_HMAC_MD5_DUPLICATE                 HmacMd5Duplicate;\r
-  EDKII_CRYPTO_HMAC_MD5_UPDATE                    HmacMd5Update;\r
-  EDKII_CRYPTO_HMAC_MD5_FINAL                     HmacMd5Final;\r
-  /// HMAC SHA1\r
-  EDKII_CRYPTO_HMAC_SHA1_NEW                      HmacSha1New;\r
-  EDKII_CRYPTO_HMAC_SHA1_FREE                     HmacSha1Free;\r
-  EDKII_CRYPTO_HMAC_SHA1_SET_KEY                  HmacSha1SetKey;\r
-  EDKII_CRYPTO_HMAC_SHA1_DUPLICATE                HmacSha1Duplicate;\r
-  EDKII_CRYPTO_HMAC_SHA1_UPDATE                   HmacSha1Update;\r
-  EDKII_CRYPTO_HMAC_SHA1_FINAL                    HmacSha1Final;\r
+  /// HMAC MD5 - deprecated and unsupported\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_NEW            DeprecatedHmacMd5New;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_FREE           DeprecatedHmacMd5Free;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_SET_KEY        DeprecatedHmacMd5SetKey;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_DUPLICATE      DeprecatedHmacMd5Duplicate;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_UPDATE         DeprecatedHmacMd5Update;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_MD5_FINAL          DeprecatedHmacMd5Final;\r
+  /// HMAC SHA1 - deprecated and unsupported\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_NEW           DeprecatedHmacSha1New;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_FREE          DeprecatedHmacSha1Free;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_SET_KEY       DeprecatedHmacSha1SetKey;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_DUPLICATE     DeprecatedHmacSha1Duplicate;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_UPDATE        DeprecatedHmacSha1Update;\r
+  DEPRECATED_EDKII_CRYPTO_HMAC_SHA1_FINAL         DeprecatedHmacSha1Final;\r

   /// HMAC SHA256\r
   EDKII_CRYPTO_HMAC_SHA256_NEW                    HmacSha256New;\r
   EDKII_CRYPTO_HMAC_SHA256_FREE                   HmacSha256Free;\r
   /// HMAC SHA256\r
   EDKII_CRYPTO_HMAC_SHA256_NEW                    HmacSha256New;\r
   EDKII_CRYPTO_HMAC_SHA256_FREE                   HmacSha256Free;\r


@@ -3911,18 +3597,18 @@ struct _EDKII_CRYPTO_PROTOCOL {
   EDKII_CRYPTO_X509_FREE                          X509Free;\r
   EDKII_CRYPTO_X509_STACK_FREE                    X509StackFree;\r
   EDKII_CRYPTO_X509_GET_TBS_CERT                  X509GetTBSCert;\r
   EDKII_CRYPTO_X509_FREE                          X509Free;\r
   EDKII_CRYPTO_X509_STACK_FREE                    X509StackFree;\r
   EDKII_CRYPTO_X509_GET_TBS_CERT                  X509GetTBSCert;\r

-  /// TDES\r
-  EDKII_CRYPTO_TDES_GET_CONTEXT_SIZE              TdesGetContextSize;\r
-  EDKII_CRYPTO_TDES_INIT                          TdesInit;\r
-  EDKII_CRYPTO_TDES_ECB_ENCRYPT                   TdesEcbEncrypt;\r
-  EDKII_CRYPTO_TDES_ECB_DECRYPT                   TdesEcbDecrypt;\r
-  EDKII_CRYPTO_TDES_CBC_ENCRYPT                   TdesCbcEncrypt;\r
-  EDKII_CRYPTO_TDES_CBC_DECRYPT                   TdesCbcDecrypt;\r
-  /// AES\r
+  /// TDES - deprecated and unsupported\r
+  DEPRECATED_EDKII_CRYPTO_TDES_GET_CONTEXT_SIZE   DeprecatedTdesGetContextSize;\r
+  DEPRECATED_EDKII_CRYPTO_TDES_INIT               DeprecatedTdesInit;\r
+  DEPRECATED_EDKII_CRYPTO_TDES_ECB_ENCRYPT        DeprecatedTdesEcbEncrypt;\r
+  DEPRECATED_EDKII_CRYPTO_TDES_ECB_DECRYPT        DeprecatedTdesEcbDecrypt;\r
+  DEPRECATED_EDKII_CRYPTO_TDES_CBC_ENCRYPT        DeprecatedTdesCbcEncrypt;\r
+  DEPRECATED_EDKII_CRYPTO_TDES_CBC_DECRYPT        DeprecatedTdesCbcDecrypt;\r
+  /// AES - ECB Mode is deprecated and unsupported\r

   EDKII_CRYPTO_AES_GET_CONTEXT_SIZE               AesGetContextSize;\r
   EDKII_CRYPTO_AES_INIT                           AesInit;\r
   EDKII_CRYPTO_AES_GET_CONTEXT_SIZE               AesGetContextSize;\r
   EDKII_CRYPTO_AES_INIT                           AesInit;\r

-  EDKII_CRYPTO_AES_ECB_ENCRYPT                    AesEcbEncrypt;\r
-  EDKII_CRYPTO_AES_ECB_DECRYPT                    AesEcbDecrypt;\r
+  DEPRECATED_EDKII_CRYPTO_AES_ECB_ENCRYPT         DeprecatedAesEcbEncrypt;\r
+  DEPRECATED_EDKII_CRYPTO_AES_ECB_DECRYPT         DeprecatedAesEcbDecrypt;\r

   EDKII_CRYPTO_AES_CBC_ENCRYPT                    AesCbcEncrypt;\r
   EDKII_CRYPTO_AES_CBC_DECRYPT                    AesCbcDecrypt;\r
   /// Arc4 - deprecated and unsupported\r
   EDKII_CRYPTO_AES_CBC_ENCRYPT                    AesCbcEncrypt;\r
   EDKII_CRYPTO_AES_CBC_DECRYPT                    AesCbcDecrypt;\r
   /// Arc4 - deprecated and unsupported\r


@@ -3982,6 +3668,9 @@ struct _EDKII_CRYPTO_PROTOCOL {
   EDKII_CRYPTO_TLS_GET_HOST_PUBLIC_CERT           TlsGetHostPublicCert;\r
   EDKII_CRYPTO_TLS_GET_HOST_PRIVATE_KEY           TlsGetHostPrivateKey;\r
   EDKII_CRYPTO_TLS_GET_CERT_REVOCATION_LIST       TlsGetCertRevocationList;\r
   EDKII_CRYPTO_TLS_GET_HOST_PUBLIC_CERT           TlsGetHostPublicCert;\r
   EDKII_CRYPTO_TLS_GET_HOST_PRIVATE_KEY           TlsGetHostPrivateKey;\r
   EDKII_CRYPTO_TLS_GET_CERT_REVOCATION_LIST       TlsGetCertRevocationList;\r

+  /// RSA PSS\r
+  EDKII_CRYPTO_RSA_PSS_SIGN                       RsaPssSign;\r
+  EDKII_CRYPTO_RSA_PSS_VERIFY                     RsaPssVerify;\r

 };\r
 \r
 extern GUID gEdkiiCryptoProtocolGuid;\r
 };\r
 \r
 extern GUID gEdkiiCryptoProtocolGuid;\r