Hello Jiewen,
On 7/26/22 03:11, Yao, Jiewen wrote:
Hi
Please allow me to clarify the position of this library class.
In this library header file, there are 4 references:
- [1] Arm True Random Number Generator Firmware, Interface 1.0,
Platform Design Document.
(https://developer.arm.com/documentation/den0098/latest/)
- [2] NIST Special Publication 800-90A Revision 1, June 2015, Recommendation
for Random Number Generation Using Deterministic Random Bit Generators.
(https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final)
- [3] NIST Special Publication 800-90B, Recommendation for the Entropy
Sources Used for Random Bit Generation.
(https://csrc.nist.gov/publications/detail/sp/800-90b/final)
- [4] (Second Draft) NIST Special Publication 800-90C, Recommendation for
Random Bit Generator (RBG) Constructions.
(https://csrc.nist.gov/publications/detail/sp/800-90c/draft)
To me, the API definition only seems align with [1] with some adjustment.
But I am not clear how that is related to [2], [3], and [4].
Question: Is this library class only for ARM TRNG firmware? Or is this generic
to follow [2], [3], [4]?
Assuming this is for ARM TRNG only, I suggest to remove [2], [3], [4], in the
library *class* definition.
You can still put [2], [3], [4] in library *instance*, as the implementation
reference.
The library class aims to be generic (as for the MdePkg), but it is indeed
following [1] closely.
I will follow the above recommendation if that's ok.
More specific, this is *TRNG* class, I think only [3] is related.
I am not clear how [2] and [4] are involved. If you can explain a little bit,
that would be good.
[2] and [4] should indeed not be referenced for this TRNG library and will be
removed.
Regards,
Pierre
Thank you
Yao, Jiewen
-----Original Message-----
From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of
PierreGondois
Sent: Friday, July 22, 2022 10:32 PM
To: devel@edk2.groups.io
Cc: Sami Mujawar <sami.muja...@arm.com>; Leif Lindholm
<quic_llind...@quicinc.com>; Ard Biesheuvel <ardb+tianoc...@kernel.org>;
Rebecca Cran <rebe...@bsdio.com>; Kinney, Michael D
<michael.d.kin...@intel.com>; Gao, Liming <gaolim...@byosoft.com.cn>; Yao,
Jiewen <jiewen....@intel.com>; Wang, Jian J <jian.j.w...@intel.com>; Pierre
Gondois <pierre.gond...@arm.com>
Subject: [edk2-devel] [PATCH v4 05/21] MdePkg/TrngLib: Definition for TRNG
library class interface
From: Sami Mujawar <sami.muja...@arm.com>
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 True Random Number Generator (TRNG) library defines an
interface to access the entropy source on a platform. Some
platforms/architectures may provide access to the entropy
using a firmware interface. In such cases the TRNG library
shall be used to provide an abstraction.
Signed-off-by: Sami Mujawar <sami.muja...@arm.com>
---
MdePkg/Include/Library/TrngLib.h | 121 +++++++++++++++++++++++++++++++
MdePkg/MdePkg.dec | 5 ++
2 files changed, 126 insertions(+)
create mode 100644 MdePkg/Include/Library/TrngLib.h
diff --git a/MdePkg/Include/Library/TrngLib.h
b/MdePkg/Include/Library/TrngLib.h
new file mode 100644
index 000000000000..a6f165b1f918
--- /dev/null
+++ b/MdePkg/Include/Library/TrngLib.h
@@ -0,0 +1,121 @@
+/** @file
+ TRNG interface library definitions.
+
+ Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>
+
+ SPDX-License-Identifier: BSD-2-Clause-Patent
+
+ @par Reference(s):
+ - [1] Arm True Random Number Generator Firmware, Interface 1.0,
+ Platform Design Document.
+ (https://developer.arm.com/documentation/den0098/latest/)
+ - [2] NIST Special Publication 800-90A Revision 1, June 2015,
Recommendation
+ for Random Number Generation Using Deterministic Random Bit
Generators.
+ (https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final)
+ - [3] NIST Special Publication 800-90B, Recommendation for the Entropy
+ Sources Used for Random Bit Generation.
+ (https://csrc.nist.gov/publications/detail/sp/800-90b/final)
+ - [4] (Second Draft) NIST Special Publication 800-90C, Recommendation for
+ Random Bit Generator (RBG) Constructions.
+ (https://csrc.nist.gov/publications/detail/sp/800-90c/draft)
+
+ @par Glossary:
+ - TRNG - True Random Number Generator
+**/
+
+#ifndef TRNG_LIB_H_
+#define TRNG_LIB_H_
+
+/** Get the version of the TRNG backend.
+
+ A TRNG may be implemented by the system firmware, in which case this
+ function shall return the version of the TRNG backend.
+ The implementation must return NOT_SUPPORTED if a Back end is not present.
+
+ @param [out] MajorRevision Major revision.
+ @param [out] MinorRevision Minor revision.
+
+ @retval RETURN_SUCCESS The function completed successfully.
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.
+ @retval RETURN_UNSUPPORTED Backend not present.
+**/
+RETURN_STATUS
+EFIAPI
+GetTrngVersion (
+ OUT UINT16 *MajorRevision,
+ OUT UINT16 *MinorRevision
+ );
+
+/** Get the UUID of the TRNG backend.
+
+ A TRNG may be implemented by the system firmware, in which case this
+ function shall return the UUID of the TRNG backend.
+ Returning the TRNG UUID is optional and if not implemented,
RETURN_UNSUPPORTED
+ shall be returned.
+
+ Note: The caller must not rely on the returned UUID as a trustworthy TRNG
+ Back end identity
+
+ @param [out] Guid UUID of the TRNG backend.
+
+ @retval RETURN_SUCCESS The function completed successfully.
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.
+ @retval RETURN_UNSUPPORTED Function not implemented.
+**/
+RETURN_STATUS
+EFIAPI
+GetTrngUuid (
+ OUT GUID *Guid
+ );
+
+/** Returns maximum number of entropy bits that can be returned in a single
+ call.
+
+ @return Returns the maximum number of Entropy bits that can be returned
+ in a single call to GetTrngEntropy().
+**/
+UINTN
+EFIAPI
+GetTrngMaxSupportedEntropyBits (
+ VOID
+ );
+
+/** Returns N bits of conditioned entropy.
+
+ See [3] Section 2.3.1 GetEntropy: An Interface to the Entropy Source
+ GetEntropy
+ Input:
+ bits_of_entropy: the requested amount of entropy
+ Output:
+ entropy_bitstring: The string that provides the requested entropy.
+ status: A Boolean value that is TRUE if the request has been satisfied,
+ and is FALSE otherwise.
+
+ Note: In this implementation this function returns a status code instead
+ of a boolean value.
+ This is also compatible with the definition of Get_Entropy, see [4]
+ Section 7.4 Entropy Source Calls.
+ (status, entropy_bitstring) = Get_Entropy (
+ requested_entropy,
+ max_length
+ )
+
+ @param [in] EntropyBits Number of entropy bits requested.
+ @param [in] BufferSize Size of the Buffer in bytes.
+ @param [out] Buffer Buffer to return the entropy bits.
+
+ @retval RETURN_SUCCESS The function completed successfully.
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.
+ @retval RETURN_UNSUPPORTED Function not implemented.
+ @retval RETURN_BAD_BUFFER_SIZE Buffer size is too small.
+ @retval RETURN_NOT_READY No Entropy available.
+**/
+RETURN_STATUS
+EFIAPI
+GetTrngEntropy (
+ IN UINTN EntropyBits,
+ IN UINTN BufferSize,
+ OUT UINT8 *Buffer
+ );
+
+#endif // TRNG_LIB_H_
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index f1ebf9e251c1..7ff26e22f915 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -7,6 +7,7 @@
# Copyright (c) 2007 - 2022, Intel Corporation. All rights reserved.<BR>
# Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
# (C) Copyright 2016 - 2021 Hewlett Packard Enterprise Development LP<BR>
+# Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>
#
# SPDX-License-Identifier: BSD-2-Clause-Patent
#
@@ -275,6 +276,10 @@ [LibraryClasses]
## @libraryclass Provides function for SMM CPU Rendezvous Library.
SmmCpuRendezvousLib|Include/Library/SmmCpuRendezvousLib.h
+ ## @libraryclass Provides services to generate Entropy using a TRNG.
+ #
+ TrngLib|Include/Library/TrngLib.h
+
[LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64]
## @libraryclass Provides services to generate random number.
#
--
2.25.1
-=-=-=-=-=-=
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#91704): https://edk2.groups.io/g/devel/message/91704
Mute This Topic: https://groups.io/mt/92548701/1772286
Group Owner: devel+ow...@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [jiewen....@intel.com]
-=-=-=-=-=-=
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#91843): https://edk2.groups.io/g/devel/message/91843
Mute This Topic: https://groups.io/mt/92548701/21656
Group Owner: devel+ow...@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com]
-=-=-=-=-=-=-=-=-=-=-=-
