uefi-raw: Add TCG protocols

Author: nicholasbishop

uefi-raw/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Changed
 
 - Added `protocol::string::UnicodeCollationProtocol`.
+- Added `protocol::tcg` module, containing the TCG v1 and v2 protocols.
 
 
 # uefi-raw - 0.9.0 (2024-10-23)

uefi-raw/src/protocol/mod.rs

@@ -18,3 +18,4 @@ pub mod network;
 pub mod rng;
 pub mod shell_params;
 pub mod string;
+pub mod tcg;

uefi-raw/src/protocol/tcg.rs

@@ -0,0 +1,18 @@
+//! [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::*;

uefi-raw/src/protocol/tcg/enums.rs

@@ -0,0 +1,75 @@
+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-raw/src/protocol/tcg/v1.rs

@@ -0,0 +1,88 @@
+//! [TCG] (Trusted Computing Group) protocol for [TPM] (Trusted Platform
+//! Module) 1.1 and 1.2.
+//!
+//! This protocol is defined in the [TCG EFI Protocol Specification _for
+//! TPM Family 1.1 or 1.2_][spec].
+//!
+//! [spec]: https://trustedcomputinggroup.org/resource/tcg-efi-protocol-specification/
+//! [TCG]: https://trustedcomputinggroup.org/
+//! [TPM]: https://en.wikipedia.org/wiki/Trusted_Platform_Module
+
+use crate::{guid, Guid, PhysicalAddress, Status};
+use core::ffi::c_void;
+
+/// Information about the protocol and the TPM device.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
+pub struct TcgBootServiceCapability {
+    pub size: u8,
+    pub structure_version: TcgVersion,
+    pub protocol_spec_version: TcgVersion,
+    pub hash_algorithm_bitmap: u8,
+    pub tpm_present_flag: u8,
+    pub tpm_deactivated_flag: u8,
+}
+
+/// Version information.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
+pub struct TcgVersion {
+    /// Major version.
+    pub major: u8,
+    /// Minor version.
+    pub minor: u8,
+
+    pub rev_major: u8,
+    pub rev_minor: u8,
+}
+
+/// Protocol for interacting with TPM 1.1 and 1.2 devices.
+#[derive(Debug)]
+#[repr(C)]
+pub struct TcgProtocol {
+    pub status_check: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        protocol_capability: *mut TcgBootServiceCapability,
+        feature_flags: *mut u32,
+        event_log_location: *mut PhysicalAddress,
+        event_log_last_entry: *mut PhysicalAddress,
+    ) -> Status,
+
+    pub hash_all: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        hash_data: *const u8,
+        hash_data_len: u64,
+        algorithm_id: u32,
+        hashed_data_len: *mut u64,
+        hashed_data_result: *mut *mut u8,
+    ) -> Status,
+
+    pub log_event: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        event: *const c_void,
+        event_number: *mut u32,
+        flags: u32,
+    ) -> Status,
+
+    pub pass_through_to_tpm: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        tpm_input_parameter_block_size: u32,
+        tpm_input_parameter_block: *const u8,
+        tpm_output_parameter_block_size: u32,
+        tpm_output_parameter_block: *mut u8,
+    ) -> Status,
+
+    pub hash_log_extend_event: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        hash_data: PhysicalAddress,
+        hash_data_len: u64,
+        algorithm_id: u32,
+        event: *mut c_void,
+        event_number: *mut u32,
+        event_log_last_entry: *mut PhysicalAddress,
+    ) -> Status,
+}
+
+impl TcgProtocol {
+    pub const GUID: Guid = guid!("f541796d-a62e-4954-a775-9584f61b9cdd");
+}

uefi-raw/src/protocol/tcg/v2.rs

@@ -0,0 +1,190 @@
+//! [TCG] (Trusted Computing Group) protocol for [TPM] (Trusted Platform
+//! Module) 2.0.
+//!
+//! This protocol is defined in the [TCG EFI Protocol Specification _TPM
+//! Family 2.0_][spec]. It is generally implemented only for TPM 2.0
+//! devices, but the spec indicates it can also be used for older TPM
+//! devices.
+//!
+//! [spec]: https://trustedcomputinggroup.org/resource/tcg-efi-protocol-specification/
+//! [TCG]: https://trustedcomputinggroup.org/
+//! [TPM]: https://en.wikipedia.org/wiki/Trusted_Platform_Module
+
+use super::EventType;
+use crate::{guid, Guid, PhysicalAddress, Status};
+use bitflags::bitflags;
+use core::ffi::c_void;
+
+/// Version information.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
+pub struct Tcg2Version {
+    /// Major version.
+    pub major: u8,
+    /// Minor version.
+    pub minor: u8,
+}
+
+bitflags! {
+    /// Event log formats supported by the firmware.
+    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
+    #[repr(transparent)]
+    pub struct Tcg2EventLogBitmap: u32 {
+        /// Firmware supports the SHA-1 log format.
+        const TCG_1_2 = 0x0000_0001;
+
+        /// Firmware supports the crypto-agile log format.
+        const TCG_2 = 0x0000_0002;
+    }
+}
+
+/// Event log formats supported by the firmware.
+pub type Tcg2EventLogFormat = Tcg2EventLogBitmap;
+
+bitflags! {
+    /// Hash algorithms the protocol can provide.
+    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
+    #[repr(transparent)]
+    pub struct Tcg2HashAlgorithmBitmap: 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;
+    }
+}
+
+/// Information about the protocol and the TPM device.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
+pub struct Tcg2BootServiceCapability {
+    /// Size of this structure.
+    pub size: u8,
+
+    /// Version of the EFI TCG2 protocol.
+    pub structure_version: Tcg2Version,
+
+    /// Version of the EFI TCG2 protocol.
+    pub protocol_version: Tcg2Version,
+
+    /// Bitmap of supported hash algorithms.
+    pub hash_algorithm_bitmap: Tcg2HashAlgorithmBitmap,
+
+    /// Event log formats supported by the firmware.
+    pub supported_event_logs: Tcg2EventLogBitmap,
+
+    /// Whether the TPM is present or not.
+    pub tpm_present_flag: u8,
+
+    /// Maximum size (in bytes) of a command that can be sent to the TPM.
+    pub max_command_size: u16,
+
+    /// Maximum size (in bytes) of a response that can be provided by the TPM.
+    pub max_response_size: u16,
+
+    /// Manufacturer ID.
+    ///
+    /// See the [TCG Vendor ID registry].
+    ///
+    /// [TCG Vendor ID registry]: https://trustedcomputinggroup.org/resource/vendor-id-registry/
+    pub manufacturer_id: u32,
+
+    /// Maximum number of supported PCR banks (hashing algorithms).
+    pub number_of_pcr_banks: u32,
+
+    /// Bitmap of currently-active PCR banks (hashing algorithms). This
+    /// is a subset of the supported algorithms in [`hash_algorithm_bitmap`].
+    ///
+    /// [`hash_algorithm_bitmap`]: Self::hash_algorithm_bitmap
+    pub active_pcr_banks: Tcg2HashAlgorithmBitmap,
+}
+
+bitflags! {
+    /// Flags for the [`Tcg::hash_log_extend_event`] function.
+    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
+    #[repr(transparent)]
+    pub struct Tcg2HashLogExtendEventFlags: u64 {
+        /// Extend an event but don't log it.
+        const EFI_TCG2_EXTEND_ONLY = 0x0000_0000_0000_0001;
+
+        /// Use when measuring a PE/COFF image.
+        const PE_COFF_IMAGE = 0x0000_0000_0000_0010;
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[repr(C, packed)]
+pub struct Tcg2EventHeader {
+    pub header_size: u32,
+    pub header_version: u16,
+    pub pcr_index: u32,
+    pub event_type: EventType,
+}
+
+/// Protocol for interacting with TPM devices.
+///
+/// This protocol can be used for interacting with older TPM 1.1/1.2
+/// devices, but most firmware only uses it for TPM 2.0.
+///
+/// The corresponding C type is `EFI_TCG2_PROTOCOL`.
+#[derive(Debug)]
+#[repr(C)]
+pub struct Tcg2Protocol {
+    pub get_capability: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        protocol_capability: *mut Tcg2BootServiceCapability,
+    ) -> Status,
+
+    pub get_event_log: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        event_log_format: Tcg2EventLogFormat,
+        event_log_location: *mut PhysicalAddress,
+        event_log_last_entry: *mut PhysicalAddress,
+        event_log_truncated: *mut u8,
+    ) -> Status,
+
+    pub hash_log_extend_event: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        flags: Tcg2HashLogExtendEventFlags,
+        data_to_hash: PhysicalAddress,
+        data_to_hash_len: u64,
+        event: *const c_void,
+    ) -> Status,
+
+    pub submit_command: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        input_parameter_block_size: u32,
+        input_parameter_block: *const u8,
+        output_parameter_block_size: u32,
+        output_parameter_block: *mut u8,
+    ) -> Status,
+
+    pub get_active_pcr_banks: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        active_pcr_banks: *mut Tcg2HashAlgorithmBitmap,
+    ) -> Status,
+
+    pub set_active_pcr_banks: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        active_pcr_banks: Tcg2HashAlgorithmBitmap,
+    ) -> Status,
+
+    pub get_result_of_set_active_pcr_banks: unsafe extern "efiapi" fn(
+        this: *mut Self,
+        operation_present: *mut u32,
+        response: *mut u32,
+    ) -> Status,
+}
+
+impl Tcg2Protocol {
+    pub const GUID: Guid = guid!("607f766c-7455-42be-930b-e4d76db2720f");
+}