SecurityPkg: Add Integration Shell Test

Author: Javagedes

SecurityPkg/Test/ShellTest/ImageValidationTestApp/Aarch64/TestData.c

@@ -0,0 +1,129 @@
+/** @file
+  Header for the Image Validation unit test application.
+
+  Defines the data structures and helpers used to drive high level secure boot image
+  validation scenarios. Each scenario points the GetVariable() hook at a `db` / `dbx`
+  signature database, selects one of the built-in PE/COFF images, calls gBS->LoadImage(),
+  and asserts the EFI_STATUS LoadImage() returns.
+
+  Copyright (c) Microsoft Corporation.
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef IMAGE_VALIDATION_TEST_APP_H_
+#define IMAGE_VALIDATION_TEST_APP_H_
+
+#include <Uefi.h>
+#include <Library/UnitTestLib.h>
+
+///
+/// Selects which built-in PE/COFF image a scenario loads. The scenario runner converts this
+/// into the corresponding image buffer and size.
+///
+typedef enum {
+  IMAGE_TYPE_UNSIGNED,      ///< A valid but unsigned PE/COFF image.
+  IMAGE_TYPE_SIGNED,        ///< An Authenticode-signed image (one signature).
+  IMAGE_TYPE_DUAL_SIGNED,   ///< An image carrying two signatures.
+  IMAGE_TYPE_MAX
+} IMAGE_TYPE;
+
+///
+/// Bit flags describing the contents of a `db` or `dbx` signature database. The scenario
+/// runner builds a serialized set of EFI_SIGNATURE_LISTs from these flags.
+///
+#define DB_STATE_EMPTY         0x00000000  ///< No signature lists (absent variable).
+#define DB_STATE_IMAGE_DIGEST  0x00000001  ///< Include the loaded image's digest (EFI_CERT_SHA256_GUID).
+#define DB_STATE_SIGNER1_LEAF_CERT          0x00000002  ///< Include signer 1 leaf certificate (EFI_CERT_X509_GUID).
+#define DB_STATE_SIGNER1_INTERMEDIATE_CERT  0x00000004  ///< Include signer 1 intermediate (inner) CA certificate.
+#define DB_STATE_SIGNER1_ROOT_CERT          0x00000008  ///< Include signer 1 root CA certificate.
+#define DB_STATE_SIGNER2_CERT               0x00000010  ///< Include signer 2 certificate (dual-signed only).
+
+///
+/// Describes a single secure boot image validation scenario.
+///
+typedef struct {
+  ///
+  /// Which built-in image to load (see IMAGE_TYPE).
+  ///
+  IMAGE_TYPE      ImageType;
+  ///
+  /// DB_STATE_* flags describing the contents of the `db` database to build.
+  ///
+  UINT32          DbState;
+  ///
+  /// DB_STATE_* flags describing the contents of the `dbx` database to build.
+  ///
+  UINT32          DbxState;
+  ///
+  /// EFI_STATUS gBS->LoadImage() is expected to return for this scenario.
+  ///
+  EFI_STATUS      ExpectedStatus;
+} SECURE_BOOT_IMAGE_TEST_SCENARIO;
+
+/**
+  Convenience initializer for a SECURE_BOOT_IMAGE_TEST_SCENARIO.
+
+  Scenario descriptions are always auto-generated from DbState, DbxState, and
+  ExpectedStatus at test-suite registration time. This macro keeps scenario definitions
+  concise while preserving tabular readability.
+**/
+#define TEST_SCENARIO(ImageType, DbState, DbxState, ExpectedStatus)  \
+  {                                                                   \
+    (ImageType),                                                      \
+    (DbState),                                                        \
+    (DbxState),                                                       \
+    (ExpectedStatus)                                                  \
+  }
+
+///
+/// A named group of scenarios registered together as one unit test suite. The suites (one
+/// per image type) are defined in Scenarios.c.
+///
+typedef struct {
+  ///
+  /// Suite title shown in the report (user presentation).
+  ///
+  CONST CHAR8                            *Title;
+  ///
+  /// Suite class name for xUnit-style reporting (e.g. "SecurityPkg.ImageValidation.Signed").
+  ///
+  CONST CHAR8                            *ClassName;
+  ///
+  /// The scenarios that belong to this suite.
+  ///
+  CONST SECURE_BOOT_IMAGE_TEST_SCENARIO  *Scenarios;
+  ///
+  /// Number of entries in Scenarios.
+  ///
+  UINTN                                  ScenarioCount;
+} SECURE_BOOT_TEST_SUITE;
+
+//
+// The image validation suites (unsigned, signed, dual-signed), defined in Scenarios.c.
+//
+extern CONST SECURE_BOOT_TEST_SUITE  mTestSuites[];
+extern CONST UINTN                   mTestSuiteCount;
+
+/**
+  Unit test body that drives a single secure boot image validation scenario.
+
+  This function is registered as the test case routine for every scenario. It reads the
+  SECURE_BOOT_IMAGE_TEST_SCENARIO passed through Context, resolves the image from ImageType,
+  builds `db` / `dbx` from the DbState / DbxState flags, points the GetVariable() hook at
+  those databases, calls gBS->LoadImage() on the image, unloads the image if it loaded, and
+  asserts that the returned EFI_STATUS matches SECURE_BOOT_IMAGE_TEST_SCENARIO.ExpectedStatus.
+
+  @param[in]  Context  A pointer to the SECURE_BOOT_IMAGE_TEST_SCENARIO that describes the
+                       inputs and expected result.
+
+  @retval  UNIT_TEST_PASSED             LoadImage() returned the expected status.
+  @retval  UNIT_TEST_ERROR_TEST_FAILED  LoadImage() returned an unexpected status.
+**/
+UNIT_TEST_STATUS
+EFIAPI
+RunImageValidationScenario (
+  IN UNIT_TEST_CONTEXT  Context
+  );
+
+#endif // IMAGE_VALIDATION_TEST_APP_H_

SecurityPkg/Test/ShellTest/ImageValidationTestApp/GenTestData.py

@@ -0,0 +1,60 @@
+## @file
+#  Unit test application for high level secure boot image Validation.
+#
+#  Drives the platform image Validation handler through a series of secure boot
+#  scenarios by injecting per-test `db` / `dbx` signature databases via a
+#  GetVariable() hook and presenting built-in PE/COFF images for Validation.
+#
+#  Copyright (c) Microsoft Corporation.
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION    = 0x00010006
+  BASE_NAME      = ImageValidationTestApp
+  FILE_GUID      = 7B1A6E2C-3C4D-4F5A-9E2B-1D6F0C8A4E11
+  MODULE_TYPE    = UEFI_APPLICATION
+  VERSION_STRING = 1.0
+  ENTRY_POINT    = DxeEntryPoint
+
+#
+# The following information is for reference only and not required by the build tools.
+#
+#  VALID_ARCHITECTURES           = X64 AARCH64
+#
+
+[Sources]
+  ImageValidationTestApp.c
+  ImageValidationTestApp.h
+  Scenarios.c
+  TestData.h
+
+[Sources.X64]
+  X64/TestData.c
+
+[Sources.AARCH64]
+  Aarch64/TestDat.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+  SecurityPkg/SecurityPkg.dec
+  UnitTestFrameworkPkg/UnitTestFrameworkPkg.dec
+
+[LibraryClasses]
+  UefiApplicationEntryPoint
+  BaseLib
+  BaseMemoryLib
+  MemoryAllocationLib
+  DebugLib
+  UefiLib
+  UefiBootServicesTableLib
+  UefiRuntimeServicesTableLib
+  UnitTestLib
+  TimerLib
+
+[Guids]
+  gEfiImageSecurityDatabaseGuid    ## CONSUMES
+  gEfiGlobalVariableGuid           ## CONSUMES
+  gEfiCertSha256Guid               ## CONSUMES
+  gEfiCertX509Guid                 ## CONSUMES

SecurityPkg/Test/ShellTest/ImageValidationTestApp/ImageValidationTestApp.c

@@ -0,0 +1,162 @@
+# ImageValidationTestApp
+
+## Overview
+
+`ImageValidationTestApp` is a UEFI shell test application that validates image authentication
+behavior before loading an image. Its purpose is to ensure the platform image validation handler
+(invoked by `LoadImage`) meets UEFI specification Secure Boot requirements based on the provided
+inputs:
+
+- Image type (unisgned, signed, dual-signed)
+- `db` (allowed signatures/hashes)
+- `dbx` (revoked signatures/hashes)
+
+## Test Framework
+
+A simple framework was created so that each test scenario specifies the image type, `db`/`dbx`
+contents, and the expected output. The framework itself follows the same flow for each test
+scenario:
+
+1. Build synthetic `db` and `dbx` databases from scenario bit flags.
+2. Hook `GetVariable` so reads the following variables return scenario controlled values:
+    - `db`
+    - `dbx`
+    - `SecureBoot`
+3. Call `LoadImage` on the scenario-selected built-in image buffer.
+4. Compare the returned `EFI_STATUS` to the scenario's expected result.
+
+The `GetVariable` hook exists only for the duration of test execution and is
+restored afterward.
+
+## Supported Image Types
+
+The test supports three image classes:
+
+1. `IMAGE_TYPE_UNSIGNED`
+    - Unsigned PE/COFF image.
+
+2. `IMAGE_TYPE_SIGNED`
+    - Single PKCS#7 Authenticode signature (`WIN_CERTIFICATE`).
+    - Signature chain includes signer 1 certificates:
+    - `SIGNER1_ROOT`
+    - `SIGNER1_INTERMEDIATE`
+    - `SIGNER1_LEAF`
+
+3. `IMAGE_TYPE_DUAL_SIGNED`
+    - Two PKCS#7 Authenticode signatures.
+    - Signature 1 is the same signer 1 chain as `IMAGE_TYPE_SIGNED`.
+    - Signature 2 is a signer chain only containing `SIGNER2`.
+
+## DB / DBX Scenario Flags
+
+Scenario inputs use `DB_STATE_*` bit flags. These flags describe what is added
+to the generated `db` or `dbx` EFI signature database for that scenario.
+
+`db` and `dbx` use the same flags. The meaning of a flag is identical in both;
+only whether it allows (`db`) or revokes (`dbx`) changes behavior.
+
+### Flag Definitions
+
+Flags can be OR-combined to place multiple signature lists into one database.
+
+1. `DB_STATE_EMPTY`
+    - `GetVariable` returns `EFI_NOT_FOUND`
+
+2. `DB_STATE_IMAGE_DIGEST`
+    - Add the image's Authenticode SHA-256 digest as an `EFI_CERT_SHA256_GUID` entry.
+
+3. `DB_STATE_SIGNER1_LEAF_CERT`
+    - Add signer 1 leaf X.509 certificate (`EFI_CERT_X509_GUID`).
+
+4. `DB_STATE_SIGNER1_INTERMEDIATE_CERT`
+    - Add signer 1 intermediate X.509 certificate.
+
+5. `DB_STATE_SIGNER1_ROOT_CERT`
+    - Add signer 1 root X.509 certificate.
+
+6. `DB_STATE_SIGNER2_CERT`
+    - Add signer 2 X.509 certificate (used by dual-signed image scenarios).
+
+## GenTestData.py
+
+`GenTestData.py` generates architecture-specific test data from input EFI
+images. It signs images, computes Authenticode digests, and emits C source data
+used by this test app.
+
+### Inputs
+
+- `--x64-image <path>`: unsigned X64 EFI image
+- `--aarch64-image <path>`: unsigned AARCH64 EFI image
+
+Provide one or both.
+
+### Outputs
+
+Generated files are written to:
+
+- `X64/TestData.c`
+- `Aarch64/TestData.c`
+
+These files include:
+
+- Unsigned, signed, and dual-signed image bytes
+- Authenticode SHA-256 digests for each image form
+- DER certificates for signer 1 chain and signer 2
+
+### Tool Requirements
+
+`GenTestData.py` requires:
+
+- `openssl`
+- `sbsign` (from `sbsigntool` / `sbsigntools` package)
+- Python 3
+
+On Ubuntu/Debian:
+
+```bash
+sudo apt update
+sudo apt install -y python3 openssl sbsigntool
+```
+
+Verify tools:
+
+```bash
+which python3
+which openssl
+which sbsign
+```
+
+### Typical Linux Usage
+
+Run from this directory:
+
+```bash
+python3 GenTestData.py \
+	--x64-image X64/HelloWorld.efi \
+	--aarch64-image Aarch64/HelloWorld.efi
+```
+
+Generate only one architecture:
+
+```bash
+python3 GenTestData.py --x64-image X64/HelloWorld.efi
+python3 GenTestData.py --aarch64-image Aarch64/HelloWorld.efi
+```
+
+### Windows With WSL
+
+Because signing tools are Linux-native in this workflow, run the script inside
+WSL.
+
+Example from PowerShell:
+
+```powershell
+wsl bash -lc "python3 GenTestData.py --x64-image X64/HelloWorld.efi --aarch64-image Aarch64/HelloWorld.efi"
+```
+
+## Notes
+
+- Scenario definitions live in `Scenarios.c`.
+- Scenario data structures and `DB_STATE_*` definitions are in
+	`ImageValidationTestApp.h`.
+- Runtime test behavior and database synthesis are in `ImageValidationTestApp.c`.