[edk2-devel] [PATCH v4 05/21] MdePkg/TrngLib: Definition for TRNG library class interface
PierreGondois
pierre.gondois at arm.com
Tue Jul 26 09:52:20 UTC 2022
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 at edk2.groups.io <devel at edk2.groups.io> On Behalf Of
>> PierreGondois
>> Sent: Friday, July 22, 2022 10:32 PM
>> To: devel at edk2.groups.io
>> Cc: Sami Mujawar <sami.mujawar at arm.com>; Leif Lindholm
>> <quic_llindhol at quicinc.com>; Ard Biesheuvel <ardb+tianocore at kernel.org>;
>> Rebecca Cran <rebecca at bsdio.com>; Kinney, Michael D
>> <michael.d.kinney at intel.com>; Gao, Liming <gaoliming at byosoft.com.cn>; Yao,
>> Jiewen <jiewen.yao at intel.com>; Wang, Jian J <jian.j.wang at intel.com>; Pierre
>> Gondois <pierre.gondois at arm.com>
>> Subject: [edk2-devel] [PATCH v4 05/21] MdePkg/TrngLib: Definition for TRNG
>> library class interface
>>
>> From: Sami Mujawar <sami.mujawar at 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.mujawar at 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+owner at edk2.groups.io
>> Unsubscribe: https://edk2.groups.io/g/devel/unsub [jiewen.yao at 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/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list