From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mx.groups.io with SMTP id smtpd.web10.899.1666971217142774403 for ; Fri, 28 Oct 2022 08:33:37 -0700 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: arm.com, ip: 217.140.110.172, mailfrom: pierre.gondois@arm.com) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 1F94A11FB; Fri, 28 Oct 2022 08:33:43 -0700 (PDT) Received: from pierre123.arm.com (unknown [10.57.3.128]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id 94AAB3F534; Fri, 28 Oct 2022 08:33:34 -0700 (PDT) From: "PierreGondois" To: devel@edk2.groups.io Cc: Sami Mujawar , Leif Lindholm , Ard Biesheuvel , Rebecca Cran , Michael D Kinney , Liming Gao , Jiewen Yao , Jian J Wang Subject: [PATCH v9 06/19] MdePkg/ArmTrngLib: Definition for Arm TRNG library class interface Date: Fri, 28 Oct 2022 17:32:46 +0200 Message-Id: <20221028153259.397445-7-Pierre.Gondois@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20221028153259.397445-1-Pierre.Gondois@arm.com> References: <20221028153259.397445-1-Pierre.Gondois@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Sami Mujawar Bugzilla: 3668 (https://bugzilla.tianocore.org/show_bug.cgi?id=3D3668) 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 --- MdePkg/Include/Library/ArmTrngLib.h | 106 ++++++++++++++++++++++++++++ MdePkg/MdePkg.dec | 5 ++ 2 files changed, 111 insertions(+) create mode 100644 MdePkg/Include/Library/ArmTrngLib.h diff --git a/MdePkg/Include/Library/ArmTrngLib.h b/MdePkg/Include/Library= /ArmTrngLib.h new file mode 100644 index 000000000000..551c24413761 --- /dev/null +++ b/MdePkg/Include/Library/ArmTrngLib.h @@ -0,0 +1,106 @@ +/** @file + Arm TRNG interface library definitions (Cf. [1]). + + Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.
+ + 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-90B, Recommendation for the Entropy + Sources Used for Random Bit Generation. + (https://csrc.nist.gov/publications/detail/sp/800-90b/final) + + @par Glossary: + - TRNG - True Random Number Generator +**/ + +#ifndef ARM_TRNG_LIB_H_ +#define ARM_TRNG_LIB_H_ + +/** Get the version of the Arm TRNG backend. + + A TRNG may be implemented by the system firmware, in which case this + function shall return the version of the Arm TRNG backend. + The implementation must return NOT_SUPPORTED if a Back end is not pres= ent. + + @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 +GetArmTrngVersion ( + OUT UINT16 *MajorRevision, + OUT UINT16 *MinorRevision + ); + +/** Get the UUID of the Arm 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 Arm 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 A= rm TRNG + Back end identity + + @param [out] Guid UUID of the Arm TRNG backend. + + @retval RETURN_SUCCESS The function completed successfully= . + @retval RETURN_INVALID_PARAMETER Invalid parameter. + @retval RETURN_UNSUPPORTED Function not implemented. +**/ +RETURN_STATUS +EFIAPI +GetArmTrngUuid ( + OUT GUID *Guid + ); + +/** Returns maximum number of entropy bits that can be returned in a sin= gle + call. + + @return Returns the maximum number of Entropy bits that can be returne= d + in a single call to GetArmTrngEntropy(). +**/ +UINTN +EFIAPI +GetArmTrngMaxSupportedEntropyBits ( + VOID + ); + +/** Returns N bits of conditioned entropy. + + See [2] 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 entrop= y. + status: A Boolean value that is TRUE if the request has been satis= fied, + and is FALSE otherwise. + + @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 +GetArmTrngEntropy ( + IN UINTN EntropyBits, + IN UINTN BufferSize, + OUT UINT8 *Buffer + ); + +#endif // ARM_TRNG_LIB_H_ diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 4c81cbd75ab2..fb28d0a5f40a 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -8,6 +8,7 @@ # Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved. # (C) Copyright 2016 - 2021 Hewlett Packard Enterprise Development LP # Copyright (c) 2022, Loongson Technology Corporation Limited. All right= s reserved.
+# Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.
# # SPDX-License-Identifier: BSD-2-Clause-Patent # @@ -279,6 +280,10 @@ [LibraryClasses] ## @libraryclass Provides function for SMM CPU Rendezvous Library. SmmCpuRendezvousLib|Include/Library/SmmCpuRendezvousLib.h =20 + ## @libraryclass Provides services to generate Entropy using a TRNG. + # + ArmTrngLib|Include/Library/ArmTrngLib.h + [LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64] ## @libraryclass Provides services to generate random number. # --=20 2.25.1