From: Pierre Gondois <Pierre.Gondois@arm.com>
The NIST Special Publication 800-90A, 800-90B and 800-90C
details how to implement a Deterministic Random Bits Generator (DRBG).
Add a library interface definition for interacting with a Drbg.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
---
MdePkg/Include/Library/DrbgLib.h | 172 +++++++++++++++++++++++++++++++
MdePkg/MdePkg.dec | 4 +
2 files changed, 176 insertions(+)
create mode 100644 MdePkg/Include/Library/DrbgLib.h
diff --git a/MdePkg/Include/Library/DrbgLib.h b/MdePkg/Include/Library/DrbgLib.h
new file mode 100644
index 000000000000..aad46dbec228
--- /dev/null
+++ b/MdePkg/Include/Library/DrbgLib.h
@@ -0,0 +1,172 @@
+/** @file
+ DRBG library.
+
+ Copyright (c) 2022, Arm Limited. All rights reserved.<BR>
+ SPDX-License-Identifier: BSD-2-Clause-Patent
+
+ @par Reference(s):
+ - [1] 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)
+ - [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)
+ - [3] (Second Draft) NIST Special Publication 800-90C, Recommendation for
+ Random Bit Generator (RBG) Constructions.
+ (https://csrc.nist.gov/publications/detail/sp/800-90c/draft)
+ - [4] NIST Special Publication 800-57 Part 1 Revision 5, May 2020,
+ Recommendation for Key Management:Part 1 - General.
+
+ @par Glossary:
+ - TRNG - True Random Number Generator
+ - Sec - Security
+ - DRBG - Deterministic Random Bits Generator
+ - CTR - Counter
+**/
+
+#ifndef DRBG_LIB_H_
+#define DRBG_LIB_H_
+
+/** Drbg Mechanisms.
+*/
+typedef enum {
+ DrbgMechansimHash = 0, ///< Hash (not supported yet)
+ DrbgMechansimHmac, ///< HMAC (not supported yet)
+ DrbgMechansimCtr, ///< CTR
+ DrbgMechansimMax ///< Maximum value.
+} DRBG_MECHANISM;
+
+/** Drbg Entropy sources.
+*/
+typedef enum {
+ /// Cf. [3] s10.3.3.1
+ /// Construction When a Conditioning Function is not Used
+ DrbgEntropyNoCondFn = 0,
+ /// Cf. [3] s10.3.3.2 (no supported yet)
+ /// Construction When a Vetted Conditioning Function is Used
+ /// and Full Entropy is Not Required)
+ DrbgEntropyNoFullEntropy,
+ /// Cf. [3] s10.3.3.3 (no supported yet)
+ /// Construction When a Vetted Conditioning Function is Used
+ /// to Obtain Full Entropy Bitstrings
+ DrbgEntropyFullEntropy,
+ /// Maximum value.
+ DrbgEntropyMax
+} DRBG_ENTROPY_SRC;
+
+/** Reseed a DRBG instance.
+
+ Implementation of Reseed_function.
+ Cf. [1] s9.2 'Reseeding a DRBG Instantiation'
+
+ @param [in] PredResRequest Indicates whether prediction resistance
+ is to be provided during the request.
+ Might not be supported by all Drbgs.
+ @param [in] AddInput An optional additional input.
+ Might not be supported by all Drbgs.
+ @param [in] AddInputLen Additional input length (in bits).
+ Might not be supported by all Drbgs.
+ @param [in, out] Handle The Drbg handle.
+
+ @retval EFI_SUCCESS Success.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+DrbgReseedFn (
+ IN BOOLEAN PredResRequest,
+ IN CONST CHAR8 *AddInput,
+ IN UINTN AddInputLen,
+ IN OUT VOID *Handle
+ );
+
+/** Create a Drbg instance.
+
+ Implementation of Instantiate_function.
+ Cf. [1] s9.1 Instantiating a DRBG
+
+ @param [in] DrbgMechanism DRBG mechanism chosen.
+ @param [in] DrbgEntropySrc Entropy source chosen.
+ @param [in] ReqSecStrength Requested security strength (in bits).
+ The security strenght granted can be different.
+ @param [in] PredRes Prediction resistance flag.
+ If relevant, instantiate a DRBG that supports
+ prediction resistance.
+ Might not be supported by all Drbgs.
+ @param [in] PersStr Personnalization string.
+ Might not be supported by all Drbgs.
+ @param [in] PersStrLen Personnalization string length (in bits).
+ Might not be supported by all Drbgs.
+ @param [out] HandlePtr Pointer containting the created Drbg handle.
+
+ @retval EFI_SUCCESS Success.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+DrbgInstantiateFn (
+ IN DRBG_MECHANISM DrbgMechanism,
+ IN DRBG_ENTROPY_SRC DrbgEntropySrc,
+ IN UINTN ReqSecStrength,
+ IN BOOLEAN PredRes,
+ IN CONST CHAR8 *PersStr,
+ IN UINTN PersStrLen,
+ OUT VOID **HandlePtr
+ );
+
+/** Generate a random number.
+
+ Implementation of Generate_function.
+ Cf. [1] s9.3.1 The Generate Function
+
+ @param [in] ReqSecStrength Requested security strength (in bits).
+ If the DrbgHandle cannot satisfy the request,
+ an error is returned.
+ @param [in] PredResReq Request prediction resistance.
+ If the DrbgHandle cannot satisfy the request,
+ an error is returned.
+ @param [in] AddInput Additional input.
+ Might not be supported by all Drbgs.
+ @param [in] AddInputLen Additional input length (in bits).
+ Might not be supported by all Drbgs.
+ @param [in] ReqNbBits Number of random bits requested.
+ @param [in, out] OutBuffer If success, contains the random bits.
+ The buffer must be at least ReqNbBits bits
+ long.
+ @param [in, out] Handle The Drbg handle.
+
+ @retval EFI_SUCCESS Success.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+DrbgGenerateFn (
+ IN UINTN ReqSecStrength,
+ IN BOOLEAN PredResReq,
+ IN CONST CHAR8 *AddInput,
+ IN UINTN AddInputLen,
+ IN UINTN ReqNbBits,
+ IN OUT UINT8 *OutBuffer,
+ IN OUT VOID *Handle
+ );
+
+/** Remove a DRBG instance.
+
+ Implementation of Uninstantiate_function.
+ Cf. [1] s9.4 Removing a DRBG Instantiation
+
+ @param [in, out] Handle The Drbg handle.
+
+ @retval EFI_SUCCESS Success.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+DrbgUninstantiateFn (
+ IN OUT VOID *Handle
+ );
+
+#endif // DRBG_LIB_H_
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 078ae9323ba6..e96f875f1e91 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -284,6 +284,10 @@ [LibraryClasses]
#
AesLib|Include/Library/AesLib.h
+ ## @libraryclass A library to have a Deterministic Random Bits Generator (DRBG).
+ #
+ DrbgLib|Include/Library/DrbgLib.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 (#90899): https://edk2.groups.io/g/devel/message/90899
Mute This Topic: https://groups.io/mt/92072284/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-