MdePkg/ArmTrngLib: Add NULL instance of Arm TRNG Library

Bugzilla: 3668 (https://bugzilla.tianocore.org/show_bug.cgi?id=3668)

The Arm True Random Number Generator (TRNG) library defines an
interface to access the entropy source on a platform. On platforms
that do not have access to an entropy source, a NULL instance of
the TRNG library may be useful to satisfy the build dependency.

Therefore, add a NULL instance of the Arm TRNG library.

Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

diff --git a/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.c b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.c
new file mode 100644 (file)
index 0000000..316d78b
--- /dev/null
+++ b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.c
@@ -0,0 +1,121 @@
+/** @file\r
+  Null version of the Arm TRNG (True Random Number Generator) services\r
+  (Cf [1]).\r
+\r
+  Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>\r
+\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+  @par Reference(s):\r
+  - [1] Arm True Random Number Generator Firmware, Interface 1.0,\r
+        Platform Design Document.\r
+        (https://developer.arm.com/documentation/den0098/latest/)\r
+  - [2] NIST Special Publication 800-90B, Recommendation for the Entropy\r
+        Sources Used for Random Bit Generation.\r
+        (https://csrc.nist.gov/publications/detail/sp/800-90b/final)\r
+\r
+  @par Glossary:\r
+    - TRNG - True Random Number Generator\r
+**/\r
+\r
+#include <Library/DebugLib.h>\r
+#include <Library/ArmTrngLib.h>\r
+\r
+/** Get the version of the Arm TRNG backend.\r
+\r
+  A TRNG may be implemented by the system firmware, in which case this\r
+  function shall return the version of the Arm TRNG backend.\r
+  The implementation must return NOT_SUPPORTED if a Back end is not present.\r
+\r
+  @param [out]  MajorRevision     Major revision.\r
+  @param [out]  MinorRevision     Minor revision.\r
+\r
+  @retval  RETURN_SUCCESS            The function completed successfully.\r
+  @retval  RETURN_INVALID_PARAMETER  Invalid parameter.\r
+  @retval  RETURN_UNSUPPORTED        Backend not present.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngVersion (\r
+  OUT UINT16  *MajorRevision,\r
+  OUT UINT16  *MinorRevision\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r
+\r
+/** Get the UUID of the Arm TRNG backend.\r
+\r
+  A TRNG may be implemented by the system firmware, in which case this\r
+  function shall return the UUID of the TRNG backend.\r
+  Returning the Arm TRNG UUID is optional and if not implemented,\r
+  RETURN_UNSUPPORTED shall be returned.\r
+\r
+  Note: The caller must not rely on the returned UUID as a trustworthy Arm TRNG\r
+        Back end identity\r
+\r
+  @param [out]  Guid              UUID of the Arm TRNG backend.\r
+\r
+  @retval  RETURN_SUCCESS            The function completed successfully.\r
+  @retval  RETURN_INVALID_PARAMETER  Invalid parameter.\r
+  @retval  RETURN_UNSUPPORTED        Function not implemented.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngUuid (\r
+  OUT GUID  *Guid\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r
+\r
+/** Returns maximum number of entropy bits that can be returned in a single\r
+    call.\r
+\r
+  @return Returns the maximum number of Entropy bits that can be returned\r
+          in a single call to GetArmTrngEntropy().\r
+**/\r
+UINTN\r
+EFIAPI\r
+GetArmTrngMaxSupportedEntropyBits (\r
+  VOID\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return 0;\r
+}\r
+\r
+/** Returns N bits of conditioned entropy.\r
+\r
+  See [2] Section 2.3.1 GetEntropy: An Interface to the Entropy Source\r
+    GetEntropy\r
+      Input:\r
+        bits_of_entropy: the requested amount of entropy\r
+      Output:\r
+        entropy_bitstring: The string that provides the requested entropy.\r
+      status: A Boolean value that is TRUE if the request has been satisfied,\r
+              and is FALSE otherwise.\r
+\r
+  @param  [in]   EntropyBits  Number of entropy bits requested.\r
+  @param  [in]   BufferSize   Size of the Buffer in bytes.\r
+  @param  [out]  Buffer       Buffer to return the entropy bits.\r
+\r
+  @retval  RETURN_SUCCESS            The function completed successfully.\r
+  @retval  RETURN_INVALID_PARAMETER  Invalid parameter.\r
+  @retval  RETURN_UNSUPPORTED        Function not implemented.\r
+  @retval  RETURN_BAD_BUFFER_SIZE    Buffer size is too small.\r
+  @retval  RETURN_NOT_READY          No Entropy available.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngEntropy (\r
+  IN  UINTN  EntropyBits,\r
+  IN  UINTN  BufferSize,\r
+  OUT UINT8  *Buffer\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r

diff --git a/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.inf b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.inf
new file mode 100644 (file)
index 0000000..256df13
--- /dev/null
+++ b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.inf
@@ -0,0 +1,30 @@
+## @file\r
+#  Null instance of the Arm TRNG (True Random Number Generator) Library.\r
+#\r
+#  Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>\r
+#\r
+#  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+#\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION                    = 1.29\r
+  BASE_NAME                      = BaseArmTrngLibNull\r
+  MODULE_UNI_FILE                = BaseArmTrngLibNull.uni\r
+  FILE_GUID                      = ABDE1C87-4F50-4B82-9133-7A79E13F69AB\r
+  MODULE_TYPE                    = BASE\r
+  VERSION_STRING                 = 1.0\r
+  LIBRARY_CLASS                  = ArmTrngLib\r
+\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64 ARM AARCH64 RISCV64\r
+#\r
+\r
+[Sources]\r
+  BaseArmTrngLibNull.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  DebugLib\r

diff --git a/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.uni b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.uni
new file mode 100644 (file)
index 0000000..876764b
--- /dev/null
+++ b/MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.uni
@@ -0,0 +1,12 @@
+// /** @file\r
+// Null Instance of the Arm TRNG (True Random Number Generator) Library.\r
+//\r
+//  Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>\r
+//\r
+// SPDX-License-Identifier: BSD-2-Clause-Patent\r
+//\r
+// **/\r
+\r
+#string STR_MODULE_ABSTRACT             #language en-US "Null instance of TRNG Library"\r
+\r
+#string STR_MODULE_DESCRIPTION          #language en-US "This library instance should be used with modules that inherit an (indirect) dependency on the ArmTrngLib class, but never actually call ArmTrngLib APIs for consuming Entropy."\r

diff --git a/MdePkg/MdeLibs.dsc.inc b/MdePkg/MdeLibs.dsc.inc
index fc6f385b304d6fa216ca49e925c79f86fb804bdb..4580481cb580885cb5aa6bc5c53ef2254fce87b5 100644 (file)
--- a/MdePkg/MdeLibs.dsc.inc
+++ b/MdePkg/MdeLibs.dsc.inc
@@ -12,6 +12,7 @@
 ##\r
 \r
 [LibraryClasses]\r
+  ArmTrngLib|MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.inf\r
   RegisterFilterLib|MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf\r
   CpuLib|MdePkg/Library/BaseCpuLib/BaseCpuLib.inf\r
   SmmCpuRendezvousLib|MdePkg/Library/SmmCpuRendezvousLibNull/SmmCpuRendezvousLibNull.inf\r

diff --git a/MdePkg/MdePkg.dsc b/MdePkg/MdePkg.dsc
index 493a13ec91974a202db05866c076f0865fc7a914..32a852dc466e09535eaf4cdc3cc789bd91440fbc 100644 (file)
--- a/MdePkg/MdePkg.dsc
+++ b/MdePkg/MdePkg.dsc
@@ -57,6 +57,7 @@
   MdePkg/Library/PciSegmentLibSegmentInfo/BasePciSegmentLibSegmentInfo.inf\r
   MdePkg/Library/PciSegmentLibSegmentInfo/DxeRuntimePciSegmentLibSegmentInfo.inf\r
   MdePkg/Library/BaseS3PciSegmentLib/BaseS3PciSegmentLib.inf\r
+  MdePkg/Library/BaseArmTrngLibNull/BaseArmTrngLibNull.inf\r
   MdePkg/Library/BasePeCoffGetEntryPointLib/BasePeCoffGetEntryPointLib.inf\r
   MdePkg/Library/BasePeCoffLib/BasePeCoffLib.inf\r
   MdePkg/Library/BasePeCoffExtraActionLibNull/BasePeCoffExtraActionLibNull.inf\r