MdePkg/ArmTrngLib: Definition for Arm TRNG library class interface

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

The NIST Special Publications 800-90A, 800-90B and 800-90C
provide recommendations for random number generation. The
NIST 800-90C, Recommendation for Random Bit Generator (RBG)
Constructions, defines the GetEntropy() interface that is
used to access the entropy source. The GetEntropy() interface
is further used by Deterministic Random Bit Generators (DRBG)
to generate random numbers.

The Arm True Random Number Generator (TRNG) library defines an
interface to access the entropy source on a platform, following
the 'Arm True Random Number Generator Firmware Interface'
specification.

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

diff --git a/MdePkg/Include/Library/ArmTrngLib.h b/MdePkg/Include/Library/ArmTrngLib.h
new file mode 100644 (file)
index 0000000..551c244
--- /dev/null
+++ b/MdePkg/Include/Library/ArmTrngLib.h
@@ -0,0 +1,106 @@
+/** @file\r
+  Arm TRNG interface library definitions (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
+#ifndef ARM_TRNG_LIB_H_\r
+#define ARM_TRNG_LIB_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
+/** 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
+/** 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
+/** 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
+#endif // ARM_TRNG_LIB_H_\r

diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index ba287d9b3cfcf158eee4c36db9dd62d46c5f8dd4..e49b2d5b5f28383a32ac96cdec159aefc199817c 100644 (file)
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -8,6 +8,7 @@
 # Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
 # (C) Copyright 2016 - 2021 Hewlett Packard Enterprise Development LP<BR>\r
 # Copyright (c) 2022, Loongson Technology Corporation Limited. All rights reserved.<BR>\r
+# Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>\r
 #\r
 # SPDX-License-Identifier: BSD-2-Clause-Patent\r
 #\r
@@ -279,6 +280,10 @@
   ## @libraryclass  Provides function for SMM CPU Rendezvous Library.\r
   SmmCpuRendezvousLib|Include/Library/SmmCpuRendezvousLib.h\r
 \r
+  ##  @libraryclass  Provides services to generate Entropy using a TRNG.\r
+  #\r
+  ArmTrngLib|Include/Library/ArmTrngLib.h\r
+\r
 [LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64]\r
   ##  @libraryclass  Provides services to generate random number.\r
   #\r