mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
SecurityPkg: Introduce TpmShellApp
Implemented a TPM UEFI shell application that can be used to test the platform's physical presence interface through the TCG2 protocol that is installed during DXE. Functionality includes verifying active PCR banks which are masked against platform support, event log replay, dumping the event log, setting active PCRs, etc. Includes documentation detailing the app and its use. Signed-off-by: Raymond Diaz <raymonddiaz@microsoft.com>
This commit is contained in:
Raymond-MS
rdiaz
parent
fb2ac429de
commit
db9650ee18
5 changed files with 1294 additions and 1 deletions
1007
SecurityPkg/Applications/TpmShellApp/TpmShellApp.c
Normal file
1007
SecurityPkg/Applications/TpmShellApp/TpmShellApp.c
Normal file
File diff suppressed because it is too large
Load diff
46
SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf
Normal file
46
SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
## @file
|
||||
# TpmShellApp.inf
|
||||
#
|
||||
# UEFI shell application for testing TPM 2.0 Physical Presence Interface
|
||||
# operations, including querying and configuring PCR banks.
|
||||
#
|
||||
# Copyright (C) Microsoft Corporation.
|
||||
# SPDX-License-Identifier: BSD-2-Clause-Patent
|
||||
#
|
||||
##
|
||||
|
||||
[Defines]
|
||||
INF_VERSION = 0x00010006
|
||||
BASE_NAME = TpmShellApp
|
||||
FILE_GUID = A3B2D4F1-7E6C-4A89-B5D0-3C1F8E2A9D07
|
||||
MODULE_TYPE = UEFI_APPLICATION
|
||||
VERSION_STRING = 1.0
|
||||
ENTRY_POINT = TpmShellAppEntry
|
||||
|
||||
#
|
||||
# The following information is for reference only and not required by the build tools.
|
||||
#
|
||||
# VALID_ARCHITECTURES = IA32 X64 AARCH64
|
||||
#
|
||||
|
||||
[Sources]
|
||||
TpmShellApp.c
|
||||
|
||||
[Packages]
|
||||
MdePkg/MdePkg.dec
|
||||
MdeModulePkg/MdeModulePkg.dec
|
||||
CryptoPkg/CryptoPkg.dec
|
||||
ShellPkg/ShellPkg.dec
|
||||
|
||||
[LibraryClasses]
|
||||
BaseLib
|
||||
BaseCryptLib
|
||||
BaseMemoryLib
|
||||
IntrinsicLib
|
||||
ShellLib
|
||||
UefiApplicationEntryPoint
|
||||
UefiBootServicesTableLib
|
||||
UefiLib
|
||||
|
||||
[Protocols]
|
||||
gEfiTcg2ProtocolGuid ## CONSUMES
|
||||
230
SecurityPkg/Applications/TpmShellApp/TpmShellApp.md
Normal file
230
SecurityPkg/Applications/TpmShellApp/TpmShellApp.md
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
# TpmShellApp
|
||||
|
||||
A UEFI shell application for testing TPM 2.0 Physical Presence Interface operations,
|
||||
including querying and configuring PCR banks. The app communicates exclusively through the
|
||||
`EFI_TCG2_PROTOCOL` — it has no direct dependencies on TPM command libraries, physical
|
||||
presence libraries, or TPM hardware.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Commands](#commands)
|
||||
- [Build Integration](#build-integration)
|
||||
- [Protocol Dependency](#protocol-dependency)
|
||||
- [Output and Debugging](#output-and-debugging)
|
||||
|
||||
## Overview
|
||||
|
||||
TpmShellApp is a `UEFI_APPLICATION` that validates TPM 2.0 PCR bank operations via the
|
||||
TCG2 Protocol. It is designed to test that a platform's Physical Presence Interface
|
||||
correctly handles PCR bank change requests, including verifying that unsupported operations
|
||||
are gracefully rejected.
|
||||
|
||||
The app uses positional command-line arguments (no flags or switches) and outputs all
|
||||
results through `Print()` (from `UefiLib`), which writes directly to the UEFI shell
|
||||
console.
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
TpmShellApp help Show usage information
|
||||
TpmShellApp get_active_pcr_banks Show supported and active PCR banks
|
||||
TpmShellApp set_active_pcr_banks <mask> Request a PCR bank configuration change
|
||||
TpmShellApp enable_all_pcr_banks Request enabling all supported PCR banks
|
||||
TpmShellApp dump_event_log Dump the TCG2 event log
|
||||
TpmShellApp replay_event_log Replay event log and verify PCRs
|
||||
TpmShellApp get_last_result Show the result of the last SetActivePcrBanks call
|
||||
```
|
||||
|
||||
### `help`
|
||||
|
||||
Prints usage information, PCR bank bitmask values, and examples.
|
||||
|
||||
### `get_active_pcr_banks`
|
||||
|
||||
Calls `Tcg2Protocol->GetCapability()` and displays:
|
||||
|
||||
- **Supported PCR banks** — algorithms the TPM hardware supports (`HashAlgorithmBitmap`).
|
||||
- **Active PCR banks** — algorithms currently enabled (`ActivePcrBanks`).
|
||||
|
||||
Both are filtered by the firmware's registered hash algorithms (see
|
||||
[Hash Algorithm Filtering](#hash-algorithm-filtering) below).
|
||||
|
||||
Example output:
|
||||
|
||||
```text
|
||||
[TPM 2.0 Information]
|
||||
|
||||
Supported PCR banks: 2
|
||||
* SHA256
|
||||
|
||||
Active PCR banks: 2
|
||||
* SHA256
|
||||
```
|
||||
|
||||
### `set_active_pcr_banks <mask>`
|
||||
|
||||
Calls `Tcg2Protocol->SetActivePcrBanks()` with the provided hex bitmask. The mask is a
|
||||
combination of `EFI_TCG2_BOOT_HASH_ALG_*` values:
|
||||
|
||||
| Value | Algorithm |
|
||||
| ----- | --------- |
|
||||
| `0x01` | SHA1 |
|
||||
| `0x02` | SHA256 |
|
||||
| `0x04` | SHA384 |
|
||||
| `0x08` | SHA512 |
|
||||
| `0x10` | SM3_256 |
|
||||
|
||||
Values can be combined: `0x06` = SHA256 + SHA384.
|
||||
|
||||
The mask parameter accepts hex with or without a `0x` prefix.
|
||||
|
||||
```text
|
||||
TpmShellApp set_active_pcr_banks 0x2 Enable SHA256 only
|
||||
TpmShellApp set_active_pcr_banks 0x6 Enable SHA256 + SHA384
|
||||
TpmShellApp set_active_pcr_banks 2 Also valid (no prefix)
|
||||
```
|
||||
|
||||
> **Note**: `SetActivePcrBanks` submits a Physical Presence request. The actual bank
|
||||
> change takes effect on the next reboot, processed by
|
||||
> `Tcg2PhysicalPresenceLibProcessRequest()` during BDS.
|
||||
|
||||
### `enable_all_pcr_banks`
|
||||
|
||||
Calls `GetCapability()` to discover all supported hash algorithms, then calls
|
||||
`SetActivePcrBanks()` with the full `HashAlgorithmBitmap`. This is equivalent to
|
||||
requesting that all supported PCR banks be enabled.
|
||||
|
||||
### `dump_event_log`
|
||||
|
||||
Calls `Tcg2Protocol->GetEventLog()` with `EFI_TCG2_EVENT_LOG_FORMAT_TCG_2` (crypto-agile
|
||||
format) to retrieve the firmware's TCG2 event log. Parses the Spec ID Event header to
|
||||
discover the hash algorithms and digest sizes, then walks each `TCG_PCR_EVENT2` entry
|
||||
displaying:
|
||||
|
||||
- **PCR index** — which PCR was extended.
|
||||
- **Event type** — the TCG event type (e.g., `EV_EFI_VARIABLE_DRIVER_CONFIG`,
|
||||
`EV_SEPARATOR`).
|
||||
- **Digest(s)** — the full hex digest for each algorithm in the event.
|
||||
- **Event data size** — the number of bytes in the event payload.
|
||||
|
||||
Prints a total event count at the end.
|
||||
|
||||
### `replay_event_log`
|
||||
|
||||
Replays the TCG2 event log to compute expected PCR values, then reads the
|
||||
actual PCR values from the TPM via `SubmitCommand` (TPM2_PCR_Read) and
|
||||
compares them.
|
||||
|
||||
For each PCR that was extended in the log, the command displays:
|
||||
|
||||
- **Replayed digest** — the PCR value computed locally by replaying all
|
||||
extend operations.
|
||||
- **Actual digest** — the current PCR value read from the TPM.
|
||||
- **Result** — `PASS` if they match, `FAIL` if they differ.
|
||||
|
||||
Prints a summary with total verified, passed, and failed counts.
|
||||
|
||||
Supports SHA1, SHA256, SHA384, and SHA512 for replay hashing. Algorithms
|
||||
not supported by `BaseCryptLib` (e.g., SM3_256) are skipped.
|
||||
|
||||
### `get_last_result`
|
||||
|
||||
Calls `Tcg2Protocol->GetResultOfSetActivePcrBanks()` which queries the Physical Presence
|
||||
library for the result of the most recent `SetActivePcrBanks` operation. Displays:
|
||||
|
||||
- **Operation present** — whether a previous operation result exists (`YES` / `NO`).
|
||||
- **Response code** — the TCG PP return code (0 = success).
|
||||
|
||||
## Build Integration
|
||||
|
||||
### INF
|
||||
|
||||
The app is defined in `SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf`:
|
||||
|
||||
| Property | Value |
|
||||
| -------- | ----- |
|
||||
| `MODULE_TYPE` | `UEFI_APPLICATION` |
|
||||
| `ENTRY_POINT` | `TpmShellAppEntry` |
|
||||
| `FILE_GUID` | `A3B2D4F1-7E6C-4A89-B5D0-3C1F8E2A9D07` |
|
||||
|
||||
Dependencies:
|
||||
|
||||
| Section | Items |
|
||||
| ------- | ----- |
|
||||
| Packages | `MdePkg`, `MdeModulePkg`, `CryptoPkg`, `ShellPkg` |
|
||||
| LibraryClasses | `BaseLib`, `BaseCryptLib`, `BaseMemoryLib`, `IntrinsicLib`, `ShellLib`, `UefiApplicationEntryPoint`, `UefiBootServicesTableLib`, `UefiLib` |
|
||||
| Protocols | `gEfiTcg2ProtocolGuid` |
|
||||
|
||||
The app intentionally has **no dependency** on `SecurityPkg`, TPM command libraries,
|
||||
physical presence libraries, or runtime services. All TPM interaction goes through the
|
||||
TCG2 Protocol.
|
||||
|
||||
### DSC
|
||||
|
||||
Add the INF to the platform DSC components section:
|
||||
|
||||
```ini
|
||||
SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf
|
||||
```
|
||||
|
||||
The platform DSC must also map `IntrinsicLib` for the `UEFI_APPLICATION` module type.
|
||||
`IntrinsicLib` provides compiler-generated `memcpy`/`memset` intrinsics that the VS2022
|
||||
toolchain emits for large memory operations such as CopyMem and ZeroMem:
|
||||
|
||||
```ini
|
||||
[LibraryClasses.common.UEFI_APPLICATION]
|
||||
IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
|
||||
```
|
||||
|
||||
The app is typically included unconditionally (outside any TPM enable guard) so it can be
|
||||
built regardless of TPM enablement. It will report a clear error when the TCG2 Protocol is
|
||||
not available.
|
||||
|
||||
### FDF
|
||||
|
||||
Add the INF to the appropriate firmware volume in the platform FDF:
|
||||
|
||||
```ini
|
||||
INF SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf
|
||||
```
|
||||
|
||||
## Protocol Dependency
|
||||
|
||||
TpmShellApp uses only `EFI_TCG2_PROTOCOL` (`gEfiTcg2ProtocolGuid`). This protocol is
|
||||
installed by `Tcg2Dxe.efi`, which requires TPM to be enabled in the platform
|
||||
configuration.
|
||||
|
||||
If the protocol is not found, the app prints:
|
||||
|
||||
```text
|
||||
TCG2 Protocol not found - Not Found
|
||||
TPM 2.0 may not be enabled on this platform.
|
||||
```
|
||||
|
||||
### Protocol Functions Used
|
||||
|
||||
| Function | Command | Purpose |
|
||||
| -------- | ------- | ------- |
|
||||
| `GetCapability` | `get_active_pcr_banks`, `enable_all_pcr_banks` | Query supported/active PCR banks |
|
||||
| `SetActivePcrBanks` | `set_active_pcr_banks`, `enable_all_pcr_banks` | Submit PP request for bank change |
|
||||
| `GetEventLog` | `dump_event_log`, `replay_event_log` | Retrieve the crypto-agile event log |
|
||||
| `SubmitCommand` | `replay_event_log` | Send TPM2_PCR_Read to read actual PCR values |
|
||||
| `GetResultOfSetActivePcrBanks` | `get_last_result` | Query result of last bank change request |
|
||||
|
||||
### Hash Algorithm Filtering
|
||||
|
||||
The `HashAlgorithmBitmap` and `ActivePcrBanks` reported by `GetCapability` are already
|
||||
filtered by the firmware's hash library configuration. The chain is:
|
||||
|
||||
1. `PcdTpm2HashMask` gates which `HashInstanceLib` modules register.
|
||||
2. `Tcg2Dxe` intersects the registered hash bitmap with the TPM's hardware capabilities.
|
||||
3. `GetCapability` only reports the intersection.
|
||||
|
||||
This means the app may not see all algorithms the TPM hardware supports. To expose
|
||||
additional algorithms, update `PcdTpm2HashMask` in the platform DSC.
|
||||
|
||||
## Output and Debugging
|
||||
|
||||
All output uses `Print()` from `UefiLib`, so it appears directly on the UEFI shell
|
||||
console — no serial log or `AdvancedLogger` configuration is required to see results.
|
||||
|
|
@ -61,7 +61,9 @@
|
|||
# For host based unit tests
|
||||
"AcceptableDependencies-HOST_APPLICATION":[],
|
||||
# For UEFI shell based apps
|
||||
"AcceptableDependencies-UEFI_APPLICATION":[],
|
||||
"AcceptableDependencies-UEFI_APPLICATION":[
|
||||
"ShellPkg/ShellPkg.dec"
|
||||
],
|
||||
"IgnoreInf": []
|
||||
},
|
||||
"DscCompleteCheck": {
|
||||
|
|
|
|||
|
|
@ -173,6 +173,12 @@
|
|||
Tpm12DeviceLib|SecurityPkg/Library/Tpm12DeviceLibTcg/Tpm12DeviceLibTcg.inf
|
||||
Tpm2DeviceLib|SecurityPkg/Library/Tpm2DeviceLibTcg2/Tpm2DeviceLibTcg2.inf
|
||||
|
||||
[LibraryClasses.common.UEFI_APPLICATION]
|
||||
IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
|
||||
ShellLib|ShellPkg/Library/UefiShellLib/UefiShellLib.inf
|
||||
FileHandleLib|MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.inf
|
||||
SortLib|MdeModulePkg/Library/UefiSortLib/UefiSortLib.inf
|
||||
|
||||
[LibraryClasses.common.DXE_SMM_DRIVER]
|
||||
HobLib|MdePkg/Library/DxeHobLib/DxeHobLib.inf
|
||||
SmmServicesTableLib|MdePkg/Library/SmmServicesTableLib/SmmServicesTableLib.inf
|
||||
|
|
@ -264,6 +270,8 @@
|
|||
UnitTestResultReportLib|UnitTestFrameworkPkg/Library/UnitTestResultReportLib/UnitTestResultReportLibConOut.inf
|
||||
}
|
||||
|
||||
SecurityPkg/Applications/TpmShellApp/TpmShellApp.inf
|
||||
|
||||
#
|
||||
# TCG Storage.
|
||||
#
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue