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.
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.
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 (#91826): https://edk2.groups.io/g/devel/message/91826
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]
-=-=-=-=-=-=-=-=-=-=-=-
