Add initial support for the TCG protocols

The TCG protocols are for interacting with TPMs, or Trusted Platform
Modules. There are two versions in common use: TPM 1.2 and TPM 2.0. The
TCG protocol is for TPM 1.x, and the TCG2 protocol can theoretically be
used for any TPM but in practice is usually implemented just for TPM
2.0.

To avoid dumping too much into one PR, this commit is an MVP that only
includes getting information from the TPM (`status_check` for v1,
`get_capability` for v2).

I've exposed the new protocols with the same name but in different
module paths:
```
uefi::proto::tcg::v1::Tcg
uefi::proto::tcg::v2::Tcg
```

There is a lot of overlap between the two protocols, and the TPM v2
protocol relies in some places on v1 (although those parts are not
included in this MVP). Also, it is common to need to support both
versions at the same time, so I expect a common usage pattern will be to
import `uefi::proto::tcg::{v1, v2}` and refer to TCG types with
`v1::...` and `v2::...`.

Author: nicholasbishop

CHANGELOG.md

@@ -13,6 +13,7 @@
   feature. (requires the **unstable** and **alloc** features)
 - Added an `core::error::Error` implementation for `Error` to ease
   integration with error-handling crates. (requires the **unstable** feature)
+- Added partial support for the TCG protocols for TPM devices under `uefi::proto::tcg`.
 
 ### Changed
 

uefi-test-runner/src/proto/mod.rs

@@ -28,6 +28,7 @@ pub fn test(image: Handle, st: &mut SystemTable<Boot>) {
         target_arch = "aarch64"
     ))]
     shim::test(bt);
+    tcg::test(bt);
 }
 
 fn find_protocol(bt: &BootServices) {
@@ -73,3 +74,4 @@ mod rng;
 ))]
 mod shim;
 mod string;
+mod tcg;

uefi-test-runner/src/proto/tcg.rs

@@ -0,0 +1,65 @@
+use uefi::proto::tcg::{v1, v2};
+use uefi::table::boot::BootServices;
+
+// Environmental note:
+//
+// QEMU does not support attaching multiple TPM devices at once, so we
+// can't test TPM v1 and v2 at the same time. To ensure that the CI
+// tests both v1 and v2, we arbitrarily choose x86_64 to test TPM v1 and
+// x86 32-bit to test TPM v2.
+//
+// This is enforced in the tests here; if the `ci` feature is enabled
+// but the TPM device of the appropriate type isn't available, the test
+// panics. If the `ci` feature is not enabled then you can freely enable
+// v1, v2, or no TPM.
+
+pub fn test_tcg_v1(bt: &BootServices) {
+    info!("Running TCG v1 test");
+
+    let handle = if let Ok(handle) = bt.get_handle_for_protocol::<v1::Tcg>() {
+        handle
+    } else if cfg!(all(feature = "ci", target_arch = "x86_64")) {
+        panic!("TPM v1 is required on x86_64 CI");
+    } else {
+        info!("No TCG handle found");
+        return;
+    };
+
+    let mut tcg = bt
+        .open_protocol_exclusive::<v1::Tcg>(handle)
+        .expect("failed to open TCG protocol");
+
+    let status = tcg.status_check().expect("failed to call status_check");
+    info!(
+        "tcg status: {:?} {}",
+        status.protocol_capability, status.feature_flags
+    );
+    for event in status.event_log.iter() {
+        info!("PCR {}: {:?}", event.pcr_index().0, event.event_type());
+    }
+}
+
+pub fn test_tcg_v2(bt: &BootServices) {
+    info!("Running TCG v2 test");
+
+    let handle = if let Ok(handle) = bt.get_handle_for_protocol::<v2::Tcg>() {
+        handle
+    } else if cfg!(all(feature = "ci", target_arch = "x86")) {
+        panic!("TPM v2 is required on x86 (32-bit) CI");
+    } else {
+        info!("No TCG handle found");
+        return;
+    };
+
+    let mut tcg = bt
+        .open_protocol_exclusive::<v2::Tcg>(handle)
+        .expect("failed to open TCG protocol");
+
+    let capability = tcg.get_capability().expect("failed to call get_capability");
+    info!("capability: {:?}", capability);
+}
+
+pub fn test(bt: &BootServices) {
+    test_tcg_v1(bt);
+    test_tcg_v2(bt);
+}

uefi/src/proto/mod.rs

@@ -75,3 +75,4 @@ pub mod rng;
 pub mod security;
 pub mod shim;
 pub mod string;
+pub mod tcg;

uefi/src/proto/tcg/enums.rs

@@ -0,0 +1,85 @@
+// Providing docstrings for each constant would be a lot of work, so
+// allow missing docs. Each type-level doc links to the relevant spec to
+// provide more info.
+//
+// Setting this at the module level so that we don't have to write it
+// above each constant. That's also why these enums are in a separate
+// module instead of `super`, since we don't want to allow missing docs
+// too broadly.
+#![allow(missing_docs)]
+
+newtype_enum! {
+    /// Algorithm identifiers.
+    ///
+    /// These values are defined in the [TCG Algorithm Registry].
+    ///
+    /// [TCG Algorithm Registry]: https://trustedcomputinggroup.org/resource/tcg-algorithm-registry/
+    pub enum AlgorithmId: u16 => {
+        ERROR = 0x0000,
+        RSA = 0x0001,
+        TDES = 0x0003,
+        SHA1 = 0x0004,
+        HMAC = 0x0005,
+        AES = 0x0006,
+        MGF1 = 0x0007,
+        KEYED_HASH = 0x0008,
+        XOR = 0x000a,
+        SHA256 = 0x000b,
+        SHA384 = 0x000c,
+        SHA512 = 0x000d,
+        NULL = 0x0010,
+        SM3_256 = 0x0012,
+        SM4 = 0x0013,
+        // TODO: there are a bunch more, but the above list is probably
+        // more than sufficient for real devices.
+    }
+}
+
+newtype_enum! {
+    /// Event types stored in the TPM event log. The event type defines
+    /// which structure type is stored in the event data.
+    ///
+    /// For details of each variant, see the [TCG PC Client Platform
+    /// Firmware Protocol Specification][spec], in particular the Events
+    /// table in the Event Logging chapter.
+    ///
+    /// [spec]: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
+    pub enum EventType: u32 => {
+        PREBOOT_CERT = 0x0000_0000,
+        POST_CODE = 0x0000_0001,
+        UNUSED = 0x0000_0002,
+        NO_ACTION = 0x0000_0003,
+        SEPARATOR = 0x0000_0004,
+        ACTION = 0x0000_0005,
+        EVENT_TAG = 0x0000_0006,
+        CRTM_CONTENTS = 0x0000_0007,
+        CRTM_VERSION = 0x0000_0008,
+        CPU_MICROCODE = 0x0000_0009,
+        PLATFORM_CONFIG_FLAGS = 0x0000_000a,
+        TABLE_OF_DEVICES = 0x0000_000b,
+        COMPACT_HASH = 0x0000_000c,
+        IPL = 0x0000_000d,
+        IPL_PARTITION_DATA = 0x0000_000e,
+        NONHOST_CODE = 0x0000_000f,
+        NONHOST_CONFIG = 0x0000_0010,
+        NONHOST_INFO = 0x0000_0011,
+        OMIT_BOOT_DEVICE_EVENTS = 0x0000_0012,
+        EFI_EVENT_BASE = 0x8000_0000,
+        EFI_VARIABLE_DRIVER_CONFIG = 0x8000_0001,
+        EFI_VARIABLE_BOOT = 0x8000_0002,
+        EFI_BOOT_SERVICES_APPLICATION = 0x8000_0003,
+        EFI_BOOT_SERVICES_DRIVER = 0x8000_0004,
+        EFI_RUNTIME_SERVICES_DRIVER = 0x8000_0005,
+        EFI_GPT_EVENT = 0x8000_0006,
+        EFI_ACTION = 0x8000_0007,
+        EFI_PLATFORM_FIRMWARE_BLOB = 0x8000_0008,
+        EFI_HANDOFF_TABLES = 0x8000_0009,
+        EFI_PLATFORM_FIRMWARE_BLOB2 = 0x8000_000a,
+        EFI_HANDOFF_TABLES2 = 0x8000_000b,
+        EFI_VARIABLE_BOOT2 = 0x8000_000c,
+        EFI_HCRTM_EVENT = 0x8000_0010,
+        EFI_VARIABLE_AUTHORITY = 0x8000_00e0,
+        EFI_SPDM_FIRMWARE_BLOB = 0x8000_00e1,
+        EFI_SPDM_FIRMWARE_CONFIG = 0x8000_00e2,
+    }
+}

uefi/src/proto/tcg/mod.rs

@@ -0,0 +1,56 @@
+//! [TCG] (Trusted Computing Group) protocols.
+//!
+//! These protocols provide access to the [TPM][tpm] (Trusted Platform Module).
+//!
+//! There are two versions of the protocol. The original protocol is in
+//! the [`v1`] module. It is used with TPM 1.1 and 1.2 devices. The
+//! newer protocol in the [`v2`] module is generally provided for TPM
+//! 2.0 devices, although the spec indicates it can be used for older
+//! TPM versions as well.
+//!
+//! [TCG]: https://trustedcomputinggroup.org/
+//! [TPM]: https://en.wikipedia.org/wiki/Trusted_Platform_Module
+
+pub mod v1;
+pub mod v2;
+
+mod enums;
+pub use enums::*;
+
+use bitflags::bitflags;
+
+/// Platform Configuration Register (PCR) index.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub struct PcrIndex(pub u32);
+
+bitflags! {
+    /// Hash algorithms the protocol can provide.
+    ///
+    /// The [`v1`] protocol only supports SHA1.
+    #[derive(Default)]
+    #[repr(transparent)]
+    pub struct HashAlgorithm: u32 {
+        /// SHA-1 hash.
+        const SHA1 = 0x0000_0001;
+
+        /// SHA-256 hash.
+        const SHA256 = 0x0000_0002;
+
+        /// SHA-384 hash.
+        const SHA384 = 0x0000_0004;
+
+        /// SHA-512 hash.
+        const SHA512 = 0x0000_0008;
+
+        /// SM3-256 hash.
+        const SM3_256 = 0x0000_0010;
+    }
+}
+
+/// Convenience function for converting from a `u32` to a `usize`
+/// without using `as` or unwrapping everywhere. This particular
+/// conversion comes up a lot in the TPM API, and it should be
+/// infallable on supported targets.
+fn usize_from_u32(val: u32) -> usize {
+    val.try_into().expect("`u32` does not fit in `usize`")
+}