[PATCH v4 1/3] SecurityPkg: add definitions for OBB verification

["Wang, Jian J" <jian.j.wang@intel.com>]

> v4: change FV_HASH_FLAG_BOOT_MODE to align with
>     HASHED_FV_FLAG_SKIP_BOOT_MODE

> v3: update per Jiewen's comments
>   - remove HASHED_FV_MAX_NUMBER
>   - update _EDKII_PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_PPI to
>     be more flexible
>   - update HASHED_FV_INFO to use UINT64 for Base and Length

https://bugzilla.tianocore.org/show_bug.cgi?id=1617

gEdkiiPeiFirmwareVolumeInfoStoredHashFvPpiGuid should be installed by
platform to pass FV hash information to the common FV verify/report
driver, in which the hash value will be calculated again based on the
information fed in and then verified.

The information passed in this PPI include:
  - FVs location in flash and length
  - Hash values for different boot mode

The hash value must be calculated in following way (if 3 FVs to calc):

  FV1 -> Hash1
  FV2 -> Hash2
  FV3 -> Hash3
  Hash1 + Hash2 + Hash3 -> HashAll

Only HashAll is stored in this PPI. The purposes for this algorithm
are two:

  1. To report each FV's hash to TCG driver and verify HashAll at the
     same time without the burden to calculate the hash twice;
  2. To save hash value storage due to potential hardware limitation

Different boot mode may have its own hash value so that each mode can
decide which FV will be verified. For example, for the sake of performance,
S3 may choose to skip some FVs verification and normal boot will verify
all FVs it concerns.

So in this PPI, each FV information has flag to indicate which boot mode
it will be taken into hash calculation.

And if multiple hash values passed in this PPI, each has a flag to indicate
which boot mode it's used for. Note one hash value supports more than one
boot modes if they're just the same.

PcdStatusCodeFvVerificationPass and PcdStatusCodeFvVerificationFail are
introduced to report status back to platform, and platform can choose how
to act upon verification success and failure.

Cc: Chao Zhang <chao.b.zhang@intel.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: "Hernandez Beltran, Jorge" <jorge.hernandez.beltran@intel.com>
Cc: Harry Han <harry.han@intel.com>
Signed-off-by: Jian J Wang <jian.j.wang@intel.com>
---
 .../Ppi/FirmwareVolumeInfoStoredHashFv.h      | 62 +++++++++++++++++++
 SecurityPkg/SecurityPkg.dec                   |  9 +++
 2 files changed, 71 insertions(+)
 create mode 100644 SecurityPkg/Include/Ppi/FirmwareVolumeInfoStoredHashFv.h

diff --git a/SecurityPkg/Include/Ppi/FirmwareVolumeInfoStoredHashFv.h b/SecurityPkg/Include/Ppi/FirmwareVolumeInfoStoredHashFv.h
new file mode 100644
index 0000000000..42f2748f92
--- /dev/null
+++ b/SecurityPkg/Include/Ppi/FirmwareVolumeInfoStoredHashFv.h
@@ -0,0 +1,62 @@
+/** @file
+PPI to describe stored hash digest for FVs.
+
+Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef __PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_H__
+#define __PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_H__
+
+#include <Ppi/FirmwareVolumeInfoPrehashedFV.h>
+
+// {7F5E4E31-81B1-47E5-9E21-1E4B5BC2F61D}
+#define EDKII_PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_PPI_GUID \
+  {0x7f5e4e31, 0x81b1, 0x47e5, {0x9e, 0x21, 0x1e, 0x4b, 0x5b, 0xc2, 0xf6, 0x1d}}
+
+//
+// Hashed FV flags.
+//
+#define HASHED_FV_FLAG_REPORT_FV_INFO_PPI     0x0000000000000001
+#define HASHED_FV_FLAG_REPORT_FV_HOB          0x0000000000000002
+#define HASHED_FV_FLAG_VERIFIED_BOOT          0x0000000000000010
+#define HASHED_FV_FLAG_MEASURED_BOOT          0x0000000000000020
+#define HASHED_FV_FLAG_SKIP_ALL               0xFFFFFFFFFFFFFF00
+#define HASHED_FV_FLAG_SKIP_BOOT_MODE(Mode)   LShiftU64 (0x100, (Mode))
+
+//
+// FV hash flags
+//
+#define FV_HASH_FLAG_BOOT_MODE(Mode)          LShiftU64 (0x100, (Mode))
+
+typedef struct _EDKII_PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_PPI
+                EDKII_PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_PPI;
+
+typedef struct _HASHED_FV_INFO {
+  UINT64                  Base;
+  UINT64                  Length;
+  UINT64                  Flag;
+} HASHED_FV_INFO;
+
+typedef struct _FV_HASH_INFO {
+  UINT64                  HashFlag;
+  UINT16                  HashAlgoId;
+  UINT16                  HashSize;
+  UINT8                   Hash[64];
+} FV_HASH_INFO;
+
+//
+// PPI used to convey FVs and hash information of a specific platform. Only one
+// instance of this PPI is allowed in the platform.
+//
+struct _EDKII_PEI_FIRMWARE_VOLUME_INFO_STORED_HASH_FV_PPI {
+  FV_HASH_INFO            HashInfo;
+  UINTN                   FvNumber;
+  HASHED_FV_INFO          FvInfo[1];
+};
+
+extern EFI_GUID gEdkiiPeiFirmwareVolumeInfoStoredHashFvPpiGuid;
+
+#endif
+
diff --git a/SecurityPkg/SecurityPkg.dec b/SecurityPkg/SecurityPkg.dec
index 1d43a69bc6..b9c04a3d13 100644
--- a/SecurityPkg/SecurityPkg.dec
+++ b/SecurityPkg/SecurityPkg.dec
@@ -187,6 +187,9 @@
 
   ## Include/Ppi/FirmwareVolumeInfoPrehashedFV.h
   gEdkiiPeiFirmwareVolumeInfoPrehashedFvPpiGuid = { 0x3ce1e631, 0x7008, 0x477c, { 0xad, 0xa7, 0x5d, 0xcf, 0xc7, 0xc1, 0x49, 0x4b } }
+ 
+  ## Include/Ppi/FirmwareVolumeInfoStoredHashFv.h
+  gEdkiiPeiFirmwareVolumeInfoStoredHashFvPpiGuid = {0x7f5e4e31, 0x81b1, 0x47e5, { 0x9e, 0x21, 0x1e, 0x4b, 0x5b, 0xc2, 0xf6, 0x1d } }
 
 #
 # [Error.gEfiSecurityPkgTokenSpaceGuid]
@@ -257,6 +260,12 @@
   # @ValidList  0x80000003 | 0x010D0000
   gEfiSecurityPkgTokenSpaceGuid.PcdStatusCodeSubClassTpmDevice|0x010D0000|UINT32|0x00000007
 
+  ## Progress Code for FV verification result.<BR><BR>
+  #  (EFI_SOFTWARE_PEI_MODULE | EFI_SUBCLASS_SPECIFIC | XXX)
+  # @Prompt Status Code for FV verification result
+  gEfiSecurityPkgTokenSpaceGuid.PcdStatusCodeFvVerificationPass|0x0303100A|UINT32|0x00010030
+  gEfiSecurityPkgTokenSpaceGuid.PcdStatusCodeFvVerificationFail|0x0303100B|UINT32|0x00010031
+
 [PcdsFixedAtBuild, PcdsPatchableInModule, PcdsDynamic, PcdsDynamicEx]
   ## Image verification policy for OptionRom. Only following values are valid:<BR><BR>
   #  NOTE: Do NOT use 0x5 and 0x2 since it violates the UEFI specification and has been removed.<BR>
-- 
2.17.1.windows.2