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 0000000000..9d389e1e9b Binary files /dev/null and b/Documentation/security/intel/fit_ibb.dia differ 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