From: "Sami Mujawar" <sami.mujawar@arm.com>
To: <devel@edk2.groups.io>
Cc: Sami Mujawar <sami.mujawar@arm.com>, <ardb+tianocore@kernel.org>,
<leif@nuviainc.com>, <rebecca@bsdio.com>, <kraxel@redhat.com>,
<michael.d.kinney@intel.com>, <gaoliming@byosoft.com.cn>,
<zhiguang.liu@intel.com>, <jiewen.yao@intel.com>,
<jian.j.wang@intel.com>, <Matteo.Carlini@arm.com>,
<Akanksha.Jain2@arm.com>, <Ben.Adderson@arm.com>, <nd@arm.com>
Subject: [PATCH v2 1/8] MdePkg: Definition for TRNG library class interface
Date: Tue, 16 Nov 2021 11:32:53 +0000 [thread overview]
Message-ID: <20211116113301.31088-2-sami.mujawar@arm.com> (raw)
In-Reply-To: <20211116113301.31088-1-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>
---
Notes:
v2:
- MdePkg\Include\Library\TrngLib.h is base type [LIMING]
library. It can use RETURN_STATUS instead of
EFI_STATUS. Then, it doesn't need to include
<Uefi/UefiBaseType.h>
- Replaced EFI_STATUS with RETURN_STATUS and [SAMI]
removed include of /UefiBaseType.h.
- MdePkg\Include\Library\TrngLib.h API parameter [LIMING]
doesn't require CONST. CONST means the value
specified by the input pointer will not be
changed in API implementation.
- Removed the use of constant pointers in the [SAMI]
TRNG API.
MdePkg/Include/Library/TrngLib.h | 121 ++++++++++++++++++++
MdePkg/MdePkg.dec | 7 +-
2 files changed, 127 insertions(+), 1 deletion(-)
diff --git a/MdePkg/Include/Library/TrngLib.h b/MdePkg/Include/Library/TrngLib.h
new file mode 100644
index 0000000000000000000000000000000000000000..082c83d0a6c67aa88c789a35b8f2f73ba7cf46cd
--- /dev/null
+++ b/MdePkg/Include/Library/TrngLib.h
@@ -0,0 +1,121 @@
+/** @file
+ TRNG interface library definitions.
+
+ Copyright (c) 2021, 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 GetEntropy().
+ If this feature is not supported MAX_UINTN is returned.
+**/
+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 [out] Buffer Buffer to return the entropy bits.
+ @param [in] Buffersize Size of the Buffer in bytes.
+
+ @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
+GetEntropy (
+ IN CONST UINTN EntropyBits,
+ OUT UINT8 *Buffer,
+ IN CONST UINTN BufferSize
+ );
+
+#endif // TRNG_LIB_H_
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 8b18415b107a03b11dc984341bb788cf9cd6e0ea..e612b5c57429d1af591de8e111f328e19a030ca0 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -7,6 +7,7 @@
# Copyright (c) 2007 - 2021, 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, Arm Limited. All rights reserved.<BR>
#
# SPDX-License-Identifier: BSD-2-Clause-Patent
#
@@ -267,11 +268,15 @@ [LibraryClasses]
#
RegisterFilterLib|Include/Library/RegisterFilterLib.h
-[LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64]
+[LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64, LibraryClasses.ARM]
## @libraryclass Provides services to generate random number.
#
RngLib|Include/Library/RngLib.h
+ ## @libraryclass Provides services to generate Entropy using a TRNG.
+ #
+ TrngLib|Include/Library/TrngLib.h
+
[LibraryClasses.IA32, LibraryClasses.X64]
## @libraryclass Abstracts both S/W SMI generation and detection.
##
--
'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'
next prev parent reply other threads:[~2021-11-16 11:33 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-16 11:32 [PATCH v2 0/8] Add Raw algorithm support using Arm FW-TRNG interface Sami Mujawar
2021-11-16 11:32 ` Sami Mujawar [this message]
2021-11-16 11:32 ` [PATCH v2 2/8] ArmPkg: PCD to select conduit for monitor calls Sami Mujawar
2021-11-24 12:07 ` Leif Lindholm
2021-11-24 13:03 ` Ard Biesheuvel
2021-11-24 13:05 ` Leif Lindholm
2021-11-24 13:07 ` Ard Biesheuvel
2021-11-24 13:25 ` Leif Lindholm
2021-11-16 11:32 ` [PATCH v2 3/8] ArmPkg: Add Arm Firmware TRNG library Sami Mujawar
2021-11-24 13:01 ` [edk2-devel] " Leif Lindholm
2021-11-25 15:23 ` Sami Mujawar
2022-03-24 9:46 ` PierreGondois
[not found] ` <80941d66-5d31-053f-388a-95efe5dbbfdf@arm.com>
2022-03-24 14:56 ` PierreGondois
2022-03-24 18:12 ` Leif Lindholm
2021-11-16 11:32 ` [PATCH v2 4/8] MdePkg: Add NULL instance of TRNG Library Sami Mujawar
2021-11-16 11:32 ` [PATCH v2 5/8] SecurityPkg: Rename RdRandGenerateEntropy to common name Sami Mujawar
2021-11-16 11:32 ` [PATCH v2 6/8] SecurityPkg: Restructure checks in RngGetInfo Sami Mujawar
2021-11-16 11:32 ` [PATCH v2 7/8] SecurityPkg: Add RawAlgorithm support using TRNG library Sami Mujawar
2021-11-16 11:33 ` [PATCH v2 8/8] ArmVirtPkg: Kvmtool: Add RNG support using FW-TRNG interface Sami Mujawar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211116113301.31088-2-sami.mujawar@arm.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox