From fa0ef81d155a913b857055c6ce81e628ff866742 Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Mon, 10 Jun 2019 20:20:29 +0200 Subject: [PATCH] Documentation: Add Intel TXT Change-Id: I9e9606d0e4294ad3552ec3b3b44629f9e732d82b Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/c/coreboot/+/33416 Tested-by: build bot (Jenkins) Reviewed-by: Subrata Banik --- Documentation/security/index.md | 6 + Documentation/security/intel/acm.md | 57 +++++++++ Documentation/security/intel/fit_ibb.dia | Bin 0 -> 3706 bytes Documentation/security/intel/fit_ibb.svg | 153 +++++++++++++++++++++++ Documentation/security/intel/txt.md | 117 +++++++++++++++++ Documentation/security/intel/txt_ibb.md | 39 ++++++ 6 files changed, 372 insertions(+) create mode 100644 Documentation/security/intel/acm.md create mode 100644 Documentation/security/intel/fit_ibb.dia create mode 100644 Documentation/security/intel/fit_ibb.svg create mode 100644 Documentation/security/intel/txt.md create mode 100644 Documentation/security/intel/txt_ibb.md diff --git a/Documentation/security/index.md b/Documentation/security/index.md index 379375b616..d5d4e2b93e 100644 --- a/Documentation/security/index.md +++ b/Documentation/security/index.md @@ -7,3 +7,9 @@ This section describes documentation about the security architecture of coreboot - [Verified Boot](vboot/index.md) - [Measured Boot](vboot/measured_boot.md) - [Memory clearing](memory_clearing.md) + +## Intel TXT + +- [Intel TXT in general](intel/txt.md) +- [Intel TXT Initial Boot Block](intel/txt_ibb.md) +- [Intel Authenticated Code Modules](intel/acm.md) diff --git a/Documentation/security/intel/acm.md b/Documentation/security/intel/acm.md new file mode 100644 index 0000000000..b7dfacde8c --- /dev/null +++ b/Documentation/security/intel/acm.md @@ -0,0 +1,57 @@ +# Intel Authenticated Code Modules + +The Authenticated Code Modules (ACMs) are Intel digitally signed modules +that contain code to be run before the traditional x86 CPU reset vector. +The ACMs can be invoked at runtime through the GETSEC instruction, too. + +A platform that wants to use Intel TXT must use two ACMs: +1. BIOS ACM + * The BIOS ACM must be present in the boot flash. + * The BIOS ACM must be referenced by the [FIT]. +2. SINIT ACM + * The SINIT ACM isn't referenced by the [FIT]. + * The SINIT ACM should be provided by the boot firmware, but bootloaders + like [TBOOT] are able to load them from the filesystem as well. + +## Retrieving ACMs + +The ACMs can be downloaded on Intel's website: +[Intel Trusted Execution Technology](https://software.intel.com/en-us/articles/intel-trusted-execution-technology) + +If you want to extract the BLOB from vendor firmware you can search for the +string ``LCP_POLICY_DATA`` or ``TXT``. + +## Header + +Every ACM has a fixed size header: + +```c +/* + * ACM Header v0.0 without dynamic part + * Chapter A.1 + * Intel TXT Software Development Guide (Document: 315168-015) + */ +struct acm_header_v0 { + uint16_t module_type; + uint16_t module_sub_type; + uint32_t header_len; + uint16_t header_version[2]; + uint16_t chipset_id; + uint16_t flags; + uint32_t module_vendor; + uint32_t date; + uint32_t size; + uint16_t txt_svn; + uint16_t se_svn; + uint32_t code_control; + uint32_t error_entry_point; + uint32_t gdt_limit; + uint32_t gdt_ptr; + uint32_t seg_sel; + uint32_t entry_point; + uint8_t reserved2[63]; +} __packed; +``` + +[FIT]: ../../soc/intel/fit.md +[TBOOT]: https://sourceforge.net/p/tboot/wiki/Home/ diff --git a/Documentation/security/intel/fit_ibb.dia b/Documentation/security/intel/fit_ibb.dia new file mode 100644 index 0000000000000000000000000000000000000000..9d389e1e9b3e42ca93ae0f24578b53e8784dd861 GIT binary patch literal 3706 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 Y)eHBa|BTE0_SK93186n%a=g_50AFuBhyVZp literal 0 HcmV?d00001 diff --git a/Documentation/security/intel/fit_ibb.svg b/Documentation/security/intel/fit_ibb.svg new file mode 100644 index 0000000000..cadf2cde6c --- /dev/null +++ b/Documentation/security/intel/fit_ibb.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4 GiB + + + FIT Ptr + + + IA32 reset vec + + + + + + + + + + + + + + + + + + + + BIOS ACM + + + BOOTBLOCK + CODE + + + uCode + + + + + + + + + + + + + + + + + + + + + + + + + + + uCode + + + + + + + + + + + + + + verstage + + + FSP + + + + + + + + + + + + + + + + + + + + + + + + + + + + + IBB + + + IBB + + + IBB + + + type 7 + + + type 7 + + + type 7 + + + + diff --git a/Documentation/security/intel/txt.md b/Documentation/security/intel/txt.md new file mode 100644 index 0000000000..f67b63942e --- /dev/null +++ b/Documentation/security/intel/txt.md @@ -0,0 +1,117 @@ +# Intel Trusted Execution Technology + +Intel TXT allows +1. Attestation of the authenticity of a platform and its operating system. +2. Assuring that an authentic operating system starts in a + trusted environment, which can then be considered trusted. +3. Providing of a trusted operating system with additional + security capabilities not available to an unproven one. + +Intel TXT requirements: + +1. Intel TXT requires a **TPM** to measure parts of the firmware before it's + run on the BSP. +2. Intel TXT requires signed **Authenticated Code Modules** ([ACM]s), provided + by Intel. +3. Intel TXT requires **CPU and Chipset** support (supported since + Intel Core 2 Duo/ICH9). + +## Authenticated Code Modules + +The ACMs are Intel digitally signed modules that contain code to be run +before the traditional x86 CPU reset vector. + +More details can be found here: [Intel ACM]. + +## Modified bootflow with Intel TXT + +With Intel TXT the first instruction executed on the BSP isn't the +*reset vector*, but the [Intel ACM]. +It initializes the TPM and measures parts of the firmware, the IBB. + +### Marking the Initial Boot Block + +Individual files in the CBFS can be marked as IBB. + +More details can be found in the [Intel TXT IBB] chapter. + +### Measurements +The IBBs (Initial Boot Blocks) are measured into TPM's PCR0 by the BIOS [ACM] +before the CPU reset vector is executed. To indentify the regions that need +to be measured, the [FIT] contains one ore multiple *Type 7* entries, that +point to the IBBs. + +### Authentication + +After the IBBs have been measured, the ACM decides if the boot firmware is +trusted. There exists two validation modes: +1. HASH Autopromotion + * Uses a known good HASH stored in TPM NVRAM + * Doesn't allow to boot a fallback IBB +2. Signed BIOS policy + * Uses a signed policy stored in flash containing multiple HASHes + * The public key HASH of BIOS policy is burned into TPM by manufacturer + * Can be updated by firmware + * Allows to boot a fallback IBB + +At the moment only *Autopromotion mode* is implemented and tested well. + +In the next step the ACM terminates and the regular x86 CPU reset vector +is being executed on the BSP. + +### Protecting Secrets in Memory + +Intel TXT sets the `Secrets in Memory` bit, whenever the launch of the SINIT +ACM was successful. +The bit is reset when leaving the *MLE* by a regular shutdown or by removing +the CMOS battery. + +When `Secrets in Memory` bit is set and the IBB isn't trusted, the memory +controller won't be unlocked, resulting in a platform that cannot access DRAM. + +When `Secrets in Memory` bit is set and the IBB is trusted, the memory +controller will be unlocked, and it's the responsibility of the firmware to +[clear all DRAM] and wipe any secrets of the MLE. +The platform will be reset after all DRAM has been wiped and will boot +with the `Secrets in Memory` bit cleared. + +### Configuring protected regions for SINIT ACM + +The memory regions used by the SINIT ACM need to be prepared and protected +against DMA attacks. +The SINIT ACM as well as the SINIT handoff data are placed in memory. + +### Locking TXT register + +As last step the TXT registers are locked. + +Whenever the SINIT ACM is invoked, it verifies that the hardware is in the +correct state. If it's not the SINIT ACM will reset the platform. + +## For developers +### Configuring Intel TXT in Kconfig +Enable ``TEE_INTEL_TXT`` and set the following: + +``TEE_INTEL_TXT_BIOSACM_FILE`` to the path of the BIOS ACM provided by Intel + +``TEE_INTEL_TXT_SINITACM_FILE`` to the path of the SINIT ACM provided by Intel +### Print TXT status as early as possible +Add platform code to print the TXT status as early as possible, as the register +is cleared on cold reset. + +## References +More information can be found here: +* [Intel TXT Software Development Guide] +* [Intel TXT enabling] +* [FIT] +* [Intel TXT Lab Handout] + +[Intel TXT IBB]: txt_ibb.md +[FIT]: ../../soc/intel/fit.md +[Intel ACM]: acm.md +[ACM]: acm.md +[FIT table]: ../../soc/intel/fit.md +[clear all DRAM]: ../memory_clearing.md +[Intel TXT Lab Handout]: https://downloadmirror.intel.com/18931/eng/Intel%20TXT%20LAB%20Handout.pdf +[Intel TXT Software Development Guide]: https://www.intel.com/content/dam/www/public/us/en/documents/guides/intel-txt-software-development-guide.pdf +[Intel TXT enabling]: https://www.intel.com/content/dam/www/public/us/en/documents/guides/txt-enabling-guide.pdf diff --git a/Documentation/security/intel/txt_ibb.md b/Documentation/security/intel/txt_ibb.md new file mode 100644 index 0000000000..56cee8dca5 --- /dev/null +++ b/Documentation/security/intel/txt_ibb.md @@ -0,0 +1,39 @@ +# Intel TXT Initial Boot Block + +The Initial Boot Block (IBB) consists out of one or more files in the CBFS. + +## Constraints + +The IBB must follow the following constrains: +* One IBB must contain the reset vector as well as the [FIT table]. +* The IBB should be as small as possible. +* The IBBs must not overlap each other. +* The IBB might overlap with microcode. +* The IBB must not overlap the BIOS ACM. +* The IBB size must be a multiple of 16. +* Either one of the following: + * The IBB must be able to train the main system memory and clear all secrets. + * If the IBB cannot train the main system memory it must verify the code + that can train the main system memory and is able to clear all secrets. + +## Identification + +To add the IBBs to the [FIT], all CBFS files are added using the `cbfstool` +with the `--ibb` flag set. +The flags sets the CBFS file attribute tag to LE `' IBB'`. + +The make system in turn adds all those files to the [FIT] as type 7. + +## Intel TXT measurements + +Each IBB is measured and extended into PCR0 by [Intel TXT], before the CPU +reset vector is executed. +The IBBs are measured in the order they are listed in the [FIT]. + +## FIT schematic + +![][fit_ibb] + +[fit_ibb]: fit_ibb.svg +[FIT]: ../../soc/intel/fit.md +[Intel TXT]: txt.md