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.web12.15929.1656530366289552746 for ; Wed, 29 Jun 2022 12:19:26 -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 3305714BF; Wed, 29 Jun 2022 12:19:26 -0700 (PDT) Received: from pierre123.home (unknown [172.31.20.19]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id F201B3F792; Wed, 29 Jun 2022 12:19:23 -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 RESEND v1 1/9] MdePkg/DrbgLib: Drbg library interface definition Date: Wed, 29 Jun 2022 21:18:38 +0200 Message-Id: <20220629191848.2619317-2-Pierre.Gondois@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220629191848.2619317-1-Pierre.Gondois@arm.com> References: <20220629191848.2619317-1-Pierre.Gondois@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Pierre Gondois 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 Signed-off-by: Sami Mujawar --- 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/Dr= bgLib.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.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + + @par Reference(s): + - [1] NIST Special Publication 800-90A Revision 1, June 2015, Recommen= dation + for Random Number Generation Using Deterministic Random Bit Gene= rators. + (https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/fina= l) + - [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 =3D 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 =3D 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 dif= ferent. + @param [in] PredRes Prediction resistance flag. + If relevant, instantiate a DRBG that sup= ports + 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 req= uest, + an error is returned. + @param [in] PredResReq Request prediction resistance. + If the DrbgHandle cannot satisfy the req= uest, + 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 bi= ts + 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 =20 + ## @libraryclass A library to have a Deterministic Random Bits Gener= ator (DRBG). + # + DrbgLib|Include/Library/DrbgLib.h + [LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64] ## @libraryclass Provides services to generate random number. # --=20 2.25.1