CryptoPkg/BaseHashApiLib: Implement Unified Hash Calculation API

https://bugzilla.tianocore.org/show_bug.cgi?id=2151

This commit introduces a Unified Hash API to calculate hash using a
hashing algorithm specified by the PCD, PcdHashApiLibPolicy. This library
interfaces with the various hashing API, such as, MD4, MD5, SHA1, SHA256,
SHA512 and SM3_256 implemented in BaseCryptLib. The user can calculate
the desired hash by setting PcdHashApiLibPolicy to appropriate value.

This feature is documented in the Bugzilla,
https://bugzilla.tianocore.org/show_bug.cgi?id=2151.

Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: Jian J Wang <jian.j.wang@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Signed-off-by: Amol N Sukerkar <amol.n.sukerkar@intel.com>
Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com>

CryptoPkg/CryptoPkg.dec

@@ -33,9 +33,29 @@
   ##
   TlsLib|Include/Library/TlsLib.h
 
+  ##  @libraryclass  Provides Unified API for different hash implementations.
+  #
+  HashApiLib|Include/Library/HashApiLib.h
+
 [Guids]
   ## Crypto package token space guid.
   gEfiCryptoPkgTokenSpaceGuid      = { 0x6bd7de60, 0x9ef7, 0x4899, { 0x97, 0xd0, 0xab, 0xff, 0xfd, 0xe9, 0x70, 0xf2 } }
 
+[PcdsFixedAtBuild, PcdsPatchableInModule, PcdsDynamic, PcdsDynamicEx]
+  ## This PCD indicates the HASH algorithm to calculate hash of data
+  #  Based on the value set, the required algorithm is chosen to calculate
+  #  the hash of data.<BR>
+  #  The default hashing algorithm for BaseHashApiLib is set to SHA256.<BR>
+  #     0x00000001    - MD4.<BR>
+  #     0x00000002    - MD5.<BR>
+  #     0x00000003    - SHA1.<BR>
+  #     0x00000004    - SHA256.<BR>
+  #     0x00000005    - SHA384.<BR>
+  #     0x00000006    - SHA512.<BR>
+  #     0x00000007    - SM3_256.<BR>
+  # @Prompt Set policy for hashing unsigned image for Secure Boot.
+  # @ValidRange 0x80000001 | 0x00000001 - 0x00000007
+  gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy|0x04|UINT8|0x00000001
+
 [UserExtensions.TianoCore."ExtraFiles"]
   CryptoPkgExtra.uni

CryptoPkg/CryptoPkg.dsc

@@ -1,7 +1,7 @@
 ## @file
 #  Cryptographic Library Package for UEFI Security Implementation.
 #
-#  Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
+#  Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR>
 #  SPDX-License-Identifier: BSD-2-Clause-Patent
 #
 ##
@@ -44,6 +44,7 @@
 
   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
+  HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 
 [LibraryClasses.ARM, LibraryClasses.AARCH64]
   #
@@ -120,6 +121,7 @@
   CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
   CryptoPkg/Library/OpensslLib/OpensslLib.inf
   CryptoPkg/Library/OpensslLib/OpensslLibCrypto.inf
+  CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 
 [Components.IA32, Components.X64]
   CryptoPkg/Library/BaseCryptLib/SmmCryptLib.inf

CryptoPkg/CryptoPkg.uni

@@ -4,7 +4,7 @@
 // This Package provides cryptographic-related libraries for UEFI security modules.
 // It also provides a test application to test libraries.
 //
-// Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
+// Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR>
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -17,3 +17,19 @@
 
 
 
+#string STR_gEfiCryptoPkgTokenSpaceGuid_PcdHashApiLibPolicy_PROMPT  #language en-US "HASH algorithm to calculate hash"
+
+#string STR_gEfiCryptoPkgTokenSpaceGuid_PcdHashApiLibPolicy_HELP  #language en-US "This PCD indicates the HASH algorithm to calculate hash of data.<BR><BR>\n"
+                                                                                        "Based on the value set, the required algorithm is chosen to calculate\n"
+                                                                                        "the hash of data.<BR>\n"
+                                                                                        "The default hashing algorithm for BaseHashApiLib is set to SHA256.<BR>\n"
+                                                                                        "0x00000001  -  MD4.<BR>\n"
+                                                                                        "0x00000002  -  MD5.<BR>\n"
+                                                                                        "0x00000003  -  SHA1.<BR>\n"
+                                                                                        "0x00000004  -  SHA256.<BR>\n"
+                                                                                        "0x00000005  -  SHA384.<BR>\n"
+                                                                                        "0x00000006  -  SHA512.<BR>\n"
+                                                                                        "0x00000007  -  SM3.<BR>"
+
+
+

CryptoPkg/Include/Library/HashApiLib.h

@@ -0,0 +1,122 @@
+/** @file
+  Unified Hash API Defines
+
+  This API when called will calculate the Hash using the
+  hashing algorithm specified by PcdHashApiLibPolicy.
+
+  Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef __BASEHASHAPILIB_H_
+#define __BASEHASHAPILIB_H_
+
+typedef VOID  *HASH_API_CONTEXT;
+
+//
+// Hash Algorithms
+//
+#define HASH_API_ALGO_INVALID    0x00000000
+#define HASH_API_ALGO_MD4        0x00000001
+#define HASH_API_ALGO_MD5        0x00000002
+#define HASH_API_ALGO_SHA1       0x00000003
+#define HASH_API_ALGO_SHA256     0x00000004
+#define HASH_API_ALGO_SHA384     0x00000005
+#define HASH_API_ALGO_SHA512     0x00000006
+#define HASH_API_ALGO_SM3_256    0x00000007
+
+/**
+  Retrieves the size, in bytes, of the context buffer required for hash operations.
+
+  @return  The size, in bytes, of the context buffer required for hash operations.
+**/
+UINTN
+EFIAPI
+HashApiGetContextSize (
+  VOID
+  );
+
+/**
+  Init hash sequence.
+
+  @param[out] HashContext   Hash context.
+
+  @retval TRUE         Hash start and HashHandle returned.
+  @retval FALSE        Hash Init unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiInit (
+  OUT HASH_API_CONTEXT  HashContext
+  );
+
+/**
+  Makes a copy of an existing hash context.
+
+  @param[in]  HashContext     Hash context.
+  @param[out] NewHashContext  New copy of hash context.
+
+  @retval TRUE         Hash context copy succeeded.
+  @retval FALSE        Hash context copy failed.
+**/
+BOOLEAN
+EFIAPI
+HashApiDuplicate (
+  IN  HASH_API_CONTEXT  HashContext,
+  OUT HASH_API_CONTEXT  NewHashContext
+  );
+
+/**
+  Update hash data.
+
+  @param[in] HashContext   Hash context.
+  @param[in] DataToHash    Data to be hashed.
+  @param[in] DataToHashLen Data size.
+
+  @retval TRUE         Hash updated.
+  @retval FALSE        Hash updated unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiUpdate (
+  IN HASH_API_CONTEXT  HashContext,
+  IN VOID              *DataToHash,
+  IN UINTN             DataToHashLen
+  );
+
+/**
+  Hash complete.
+
+  @param[in]  HashContext  Hash context.
+  @param[out] Digest       Hash Digest.
+
+  @retval TRUE         Hash complete and Digest is returned.
+  @retval FALSE        Hash complete unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiFinal (
+  IN  HASH_API_CONTEXT  HashContext,
+  OUT UINT8             *Digest
+  );
+
+/**
+  Computes hash message digest of a input data buffer.
+
+  @param[in]  DataToHash     Data to be hashed.
+  @param[in]  DataToHashLen  Data size.
+  @param[out] Digest         Hash Digest.
+
+  @retval TRUE   Hash digest computation succeeded.
+  @retval FALSE  Hash digest computation failed.
+**/
+BOOLEAN
+EFIAPI
+HashApiHashAll (
+  IN  CONST VOID  *DataToHash,
+  IN  UINTN       DataToHashLen,
+  OUT UINT8       *Digest
+  );
+
+#endif

CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.c

@@ -0,0 +1,330 @@
+/** @file
+  Unified Hash API Implementation
+
+  This file implements the Unified Hash API.
+
+  This API, when called, will calculate the Hash using the
+  hashing algorithm specified by PcdHashApiLibPolicy.
+
+  Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Base.h>
+#include <Library/BaseLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/MemoryAllocationLib.h>
+#include <Library/BaseCryptLib.h>
+#include <Library/DebugLib.h>
+#include <Library/PcdLib.h>
+#include <Library/HashApiLib.h>
+
+/**
+  Retrieves the size, in bytes, of the context buffer required for hash operations.
+
+  @return  The size, in bytes, of the context buffer required for hash operations.
+**/
+UINTN
+EFIAPI
+HashApiGetContextSize (
+  VOID
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512GetContextSize ();
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3GetContextSize ();
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return 0;
+      break;
+  }
+}
+
+/**
+  Init hash sequence.
+
+  @param[out] HashContext   Hash context.
+
+  @retval TRUE         Hash start and HashHandle returned.
+  @retval FALSE        Hash Init unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiInit (
+  OUT HASH_API_CONTEXT  HashContext
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512Init (HashContext);
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3Init (HashContext);
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return FALSE;
+      break;
+  }
+}
+
+/**
+  Makes a copy of an existing hash context.
+
+  @param[in]  HashContext     Hash context.
+  @param[out] NewHashContext  New copy of hash context.
+
+  @retval TRUE         Hash context copy succeeded.
+  @retval FALSE        Hash context copy failed.
+**/
+BOOLEAN
+EFIAPI
+HashApiDuplicate (
+  IN  HASH_API_CONTEXT  HashContext,
+  OUT HASH_API_CONTEXT  NewHashContext
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512Duplicate (HashContext, NewHashContext);
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3Duplicate (HashContext, NewHashContext);
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return FALSE;
+      break;
+  }
+}
+
+/**
+  Update hash data.
+
+  @param[in] HashContext   Hash context.
+  @param[in] DataToHash    Data to be hashed.
+  @param[in] DataToHashLen Data size.
+
+  @retval TRUE         Hash updated.
+  @retval FALSE        Hash updated unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiUpdate (
+  IN HASH_API_CONTEXT  HashContext,
+  IN VOID              *DataToHash,
+  IN UINTN             DataToHashLen
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3Update (HashContext, DataToHash, DataToHashLen);
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return FALSE;
+      break;
+  }
+}
+
+/**
+  Hash complete.
+
+  @param[in]  HashContext  Hash context.
+  @param[out] Digest       Hash Digest.
+
+  @retval TRUE         Hash complete and Digest is returned.
+  @retval FALSE        Hash complete unsuccessful.
+**/
+BOOLEAN
+EFIAPI
+HashApiFinal (
+  IN  HASH_API_CONTEXT  HashContext,
+  OUT UINT8             *Digest
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512Final (HashContext, Digest);
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3Final (HashContext, Digest);
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return FALSE;
+      break;
+  }
+}
+
+/**
+  Computes hash message digest of a input data buffer.
+
+  @param[in]  DataToHash     Data to be hashed.
+  @param[in]  DataToHashLen  Data size.
+  @param[out] Digest         Hash Digest.
+
+  @retval TRUE   Hash digest computation succeeded.
+  @retval FALSE  Hash digest computation failed.
+**/
+BOOLEAN
+EFIAPI
+HashApiHashAll (
+  IN  CONST VOID  *DataToHash,
+  IN  UINTN       DataToHashLen,
+  OUT UINT8       *Digest
+  )
+{
+  switch (PcdGet8 (PcdHashApiLibPolicy)) {
+    case HASH_API_ALGO_MD4:
+      return Md4HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_MD5:
+      return Md5HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA1:
+      return Sha1HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA256:
+      return Sha256HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA384:
+      return Sha384HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_SHA512:
+      return Sha512HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    case HASH_API_ALGO_SM3_256:
+      return Sm3HashAll (DataToHash, DataToHashLen, Digest);
+      break;
+
+    default:
+      ASSERT (FALSE);
+      return FALSE;
+      break;
+  }
+}

CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf

@@ -0,0 +1,44 @@
+## @file
+#  Provides Unified API for Hash Calculation
+#
+#  This library is BaseHashApiLib. It will redirect hash request to
+#  each individual hash API, such as SHA1, SHA256, SHA384, SM3 based
+#  on hashing algorithm specified by PcdHashApiLibPolicy.
+#
+# Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x00010005
+  BASE_NAME                      = BaseHashApiLib
+  MODULE_UNI_FILE                = BaseHashApiLib.uni
+  FILE_GUID                      = B1E566DD-DE7C-4F04-BDA0-B1295D3BE927
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = BaseHashApiLib
+
+#
+# The following information is for reference only and not required by the build tools.
+#
+#  VALID_ARCHITECTURES           = IA32 X64
+#
+
+[Sources]
+  BaseHashApiLib.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+  CryptoPkg/CryptoPkg.dec
+
+[LibraryClasses]
+  BaseLib
+  BaseMemoryLib
+  DebugLib
+  MemoryAllocationLib
+  BaseCryptLib
+  PcdLib
+
+[Pcd]
+  gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy    ## CONSUMES

CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.uni

@@ -0,0 +1,17 @@
+// /** @file
+// Provides Unified API for Hash Calculation
+//
+// This library is BaseHashApiLib. It will redirect hash request to
+// each individual hash API, such as SHA1, SHA256, SHA384, SM3 based
+// on hashing algorithm specified by PcdHashApiLibPolicy.
+//
+// Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+//
+// SPDX-License-Identifier: BSD-2-Clause-Patent
+//
+// **/
+
+
+#string STR_MODULE_ABSTRACT             #language en-US "Provides hash service by specified hash handler"
+
+#string STR_MODULE_DESCRIPTION          #language en-US "This library is Unified Hash API. It will redirect hash request to the hash handler specified by PcdHashApiLibPolicy."