Re: [edk2-devel] [PATCH v4 05/21] MdePkg/TrngLib: Definition for TRNG library class interface

["PierreGondois" <pierre.gondois@arm.com>]

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.mujawar@arm.com>; Leif Lindholm
>> <quic_llindhol@quicinc.com>; Ard Biesheuvel <ardb+tianocore@kernel.org>;
>> Rebecca Cran <rebecca@bsdio.com>; Kinney, Michael D
>> <michael.d.kinney@intel.com>; Gao, Liming <gaoliming@byosoft.com.cn>; Yao,
>> Jiewen <jiewen.yao@intel.com>; Wang, Jian J <jian.j.wang@intel.com>; Pierre
>> Gondois <pierre.gondois@arm.com>
>> Subject: [edk2-devel] [PATCH v4 05/21] MdePkg/TrngLib: Definition for TRNG
>> library class interface
>>
>> From: Sami Mujawar <sami.mujawar@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@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@edk2.groups.io
>> Unsubscribe: https://edk2.groups.io/g/devel/unsub [jiewen.yao@intel.com]
>> -=-=-=-=-=-=
>>
>