[PATCH RESEND v1 5/9] MdePkg/DrbgLib: Add common wrappers

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

From: Pierre Gondois <pierre.gondois@arm.com>

Add common wrappers around the TRNG and AES libraries:
 - GetEntropy() relies an Arm Trng
 - BlockEncrypt relies on Arm implementation of the AES library

Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
---
 MdePkg/Library/DrbgLib/Common.c | 249 ++++++++++++++++++++++++++++++++
 MdePkg/Library/DrbgLib/Common.h |  74 ++++++++++
 2 files changed, 323 insertions(+)
 create mode 100644 MdePkg/Library/DrbgLib/Common.c
 create mode 100644 MdePkg/Library/DrbgLib/Common.h

diff --git a/MdePkg/Library/DrbgLib/Common.c b/MdePkg/Library/DrbgLib/Common.c
new file mode 100644
index 000000000000..0aa0459f0b0f
--- /dev/null
+++ b/MdePkg/Library/DrbgLib/Common.c
@@ -0,0 +1,249 @@
+/** @file
+  Implementation of arch specific functions for the 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.
+        (https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final)
+
+  @par Glossary:
+    - TRNG - True Random Number Generator
+    - Sec  - Security
+    - DRBG - Deterministic Random Bits Generator
+    - CTR  - Counter
+**/
+
+#include <Library/AesLib.h>
+#include <Library/BaseLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
+#include <Library/TrngLib.h>
+
+#include "Common.h"
+#include "CtrDrbg.h"
+
+/** GetEntropy implementation using Arm Trng.
+
+  Cf. [3] 10.3.1.2 Condensing After Entropy Collection
+
+  The min and max entropy length are in the DrbgHandle.
+
+  @param [in]   DrbgHandle        The Drbg hanble.
+  @param [in]   ReqEntropy        Requested entropy.
+  @param [out]  EntropyBitsStream Stream containing the generated entropy.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_ABORTED             An error occured.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+GetEntropy (
+  IN  DRBG_HANDLE  DrbgHandle,
+  IN  UINTN        ReqEntropy,
+  OUT BIT_STREAM   **EntropyBitsStream
+  )
+{
+  EFI_STATUS  Status;
+  UINTN       TrngCollectedEntropy;
+  UINTN       TrngReqBits;
+  UINTN       TrngMaxBits;
+  UINTN       TrngMaxBytes;
+  UINTN       MinLen;
+  UINT8       *QueriedBitsBuff;
+
+  if ((DrbgHandle == NULL)        ||
+      (EntropyBitsStream == NULL) ||
+      (*EntropyBitsStream != NULL))
+  {
+    ASSERT (DrbgHandle != NULL);
+    ASSERT (EntropyBitsStream != NULL);
+    ASSERT (*EntropyBitsStream == NULL);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  MinLen          = 0;
+  TrngMaxBits     = GetTrngMaxSupportedEntropyBits ();
+  TrngMaxBytes    = BitsToUpperBytes (TrngMaxBits);
+  QueriedBitsBuff = NULL;
+
+  // 1. If requested_entropy > max_length, return an error indication
+  // and a null value for the entropy_bitstring.
+  //
+  // Note: we also check for MinLen
+  if ((ReqEntropy > DrbgHandle->DrbgVal.MaxLen) ||
+      (ReqEntropy < DrbgHandle->DrbgVal.MinLen))
+  {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // 2. collected_entropy = 0.
+  TrngCollectedEntropy = 0;
+
+  // 3. entropy_bitstring = the Null string.
+  Status = BitStreamAlloc (ReqEntropy, EntropyBitsStream);
+  if (EFI_ERROR (Status)) {
+    ASSERT_EFI_ERROR (Status);
+    return Status;
+  }
+
+  QueriedBitsBuff = (UINT8 *)AllocateZeroPool (TrngMaxBytes);
+  if (QueriedBitsBuff == NULL) {
+    Status = EFI_OUT_OF_RESOURCES;
+    ASSERT_EFI_ERROR (Status);
+    goto ErrorHandler;
+  }
+
+  // 4. While collected_entropy < requested_entropy
+  while (TrngCollectedEntropy < ReqEntropy) {
+    TrngReqBits = MIN ((MinLen - TrngCollectedEntropy), TrngMaxBits);
+
+    // 4.1 Query one or more entropy sources to obtain queried_bits and the
+    // assessed_entropy for those bits.
+    //
+    // Cf. Arm True Random Number Generator Firmware, Interface 1.0,
+    // s2.4.2 Usage, the number of bits requested to the TRNG equals the
+    // number of bits returned. So assessed_entropy == #queried_bits
+    Status = GetTrngEntropy (TrngReqBits, TrngMaxBytes, QueriedBitsBuff);
+    if (EFI_ERROR (Status)) {
+      ASSERT_EFI_ERROR (Status);
+      goto ErrorHandler;
+    }
+
+    // 4.2 entropy_bitstring = entropy_bitstring || queried_bits.
+    //
+    // We are concatenating the other way around. Since this is a TRNG and
+    // the endianness of queried_bits is meaningless, this is the same.
+    Status = BitStreamWrite (
+               QueriedBitsBuff,
+               TrngCollectedEntropy,
+               TrngReqBits,
+               *EntropyBitsStream
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT_EFI_ERROR (Status);
+      goto ErrorHandler;
+    }
+
+    // 4.3 collected_entropy = collected_entropy + assessed_entropy.
+    //
+    // Cf above, for Arm TRNG, assessed_entropy == #queried_bits
+    TrngCollectedEntropy += TrngReqBits;
+  } // while
+
+  // 6. If (n > max_length), then
+  // entropy_bitstring = df(entropy_bitstring, max_length).
+  //
+  // Note: This cannot happen.
+  if (DrbgHandle->DrbgVal.MaxLen != 0) {
+    Status = EFI_ABORTED;
+    ASSERT_EFI_ERROR (Status);
+    goto ErrorHandler;
+  }
+
+  FreePool (QueriedBitsBuff);
+
+  // 7. Return (SUCCESS, entropy_bitstring).
+  return Status;
+
+ErrorHandler:
+  if (QueriedBitsBuff) {
+    FreePool (QueriedBitsBuff);
+  }
+
+  BitStreamFree (EntropyBitsStream);
+  return Status;
+}
+
+/** Block encryption (for AES).
+
+  Cf. [1] s10.3.3 'BCC and Block_Encrypt'.
+
+  @param [in]   DrbgHandle      The Drbg hanble.
+  @param [out]  OutBlockStream  Stream containing the encrypted block.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+BlockEncrypt (
+  IN  DRBG_HANDLE  DrbgHandle,
+  OUT BIT_STREAM   **OutBlockStream
+  )
+{
+  EFI_STATUS             Status;
+  AES_CTX                AesCtx;
+  CTR_INTERNAL_STATE     *CtrIntState;
+  CTR_VALUE_DEFINITIONS  *CtrVal;
+
+  if ((DrbgHandle == NULL)                  ||
+      (DrbgHandle->IntState.DrbgAlgoIntState == NULL) ||
+      (DrbgHandle->DrbgVal.DrbgAlgoVal == NULL) ||
+      (OutBlockStream == NULL)              ||
+      (*OutBlockStream != NULL))
+  {
+    ASSERT (DrbgHandle != NULL);
+    ASSERT (DrbgHandle->IntState.DrbgAlgoIntState != NULL);
+    ASSERT (DrbgHandle->DrbgVal.DrbgAlgoVal != NULL);
+    ASSERT (OutBlockStream != NULL);
+    ASSERT (*OutBlockStream == NULL);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  CtrVal      = (CTR_VALUE_DEFINITIONS *)DrbgHandle->DrbgVal.DrbgAlgoVal;
+  CtrIntState = (CTR_INTERNAL_STATE *)DrbgHandle->IntState.DrbgAlgoIntState;
+  if (IsBitStreamEmpty (CtrIntState->Key)  ||
+      IsBitStreamEmpty (CtrIntState->Val)
+      )
+  {
+    ASSERT (!IsBitStreamEmpty (CtrIntState->Key));
+    ASSERT (!IsBitStreamEmpty (CtrIntState->Val));
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Status = AesInitCtx (
+             BitStreamData (CtrIntState->Key),
+             BitStreamBitLen (CtrIntState->Key),
+             &AesCtx
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT_EFI_ERROR (Status);
+    return Status;
+  }
+
+  Status = BitStreamAlloc (CtrVal->BlockLen, OutBlockStream);
+  if (EFI_ERROR (Status)) {
+    ASSERT_EFI_ERROR (Status);
+    return Status;
+  }
+
+  Status = AesEncrypt (
+             &AesCtx,
+             BitStreamData (CtrIntState->Val),
+             BitStreamData (*OutBlockStream)
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT_EFI_ERROR (Status);
+    BitStreamFree (OutBlockStream);
+    // Fall through.
+  }
+
+  return Status;
+}
diff --git a/MdePkg/Library/DrbgLib/Common.h b/MdePkg/Library/DrbgLib/Common.h
new file mode 100644
index 000000000000..f226528bc5c2
--- /dev/null
+++ b/MdePkg/Library/DrbgLib/Common.h
@@ -0,0 +1,74 @@
+/** @file
+  Implementation of arch specific functions for the 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.
+        (https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final)
+
+  @par Glossary:
+    - TRNG - True Random Number Generator
+    - Sec  - Security
+    - DRBG - Deterministic Random Bits Generator
+    - CTR  - Counter
+**/
+
+#ifndef ARCH_IMPLEM_H_
+#define ARCH_IMPLEM_H_
+
+#include "DrbgLibInternal.h"
+
+/** GetEntropy implementation using Arm Trng.
+
+  Cf. [3] 10.3.1.2 Condensing After Entropy Collection
+
+  The min and max entropy length are in the DrbgHandle.
+
+  @param [in]   DrbgHandle        The Drbg hanble.
+  @param [in]   ReqEntropy        Requested entropy.
+  @param [out]  EntropyBitsStream Stream containing the generated entropy.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_ABORTED             An error occured.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+GetEntropy (
+  IN  DRBG_HANDLE  DrbgHandle,
+  IN  UINTN        ReqEntropy,
+  OUT BIT_STREAM   **EntropyBitsStream
+  );
+
+/** Block encryption (for AES).
+
+  Cf. [1] s10.3.3 'BCC and Block_Encrypt'.
+
+  @param [in]   DrbgHandle      The Drbg hanble.
+  @param [out]  OutBlockStream  Stream containing the encrypted block.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Out of resources.
+**/
+EFI_STATUS
+EFIAPI
+BlockEncrypt (
+  IN  DRBG_HANDLE  DrbgHandle,
+  OUT BIT_STREAM   **OutBlockStream
+  );
+
+#endif // ARCH_IMPLEM_H_
-- 
2.25.1