Documentation: Add Intel TXT

Change-Id: I9e9606d0e4294ad3552ec3b3b44629f9e732d82b
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/33416
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Subrata Banik <subrata.banik@intel.com>

5 files changed, 366 insertions, 0 deletions

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
--- /dev/null
+++ b/Documentation/security/intel/fit_ibb.dia
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 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="16cm" height="36cm" viewBox="522 318 306 714" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <rect style="fill: #ffffff" x="523.768" y="829.25" width="296.25" height="201.75"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="523.768" y="829.25" width="296.25" height="201.75"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="689.334" y="321.666" width="72.375" height="269.168"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="689.334" y="321.666" width="72.375" height="269.168"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="725.522" y="460.15">
+      <tspan x="725.522" y="460.15"></tspan>
+    </text>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="686.166" y1="352" x2="781.166" y2="352"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="685.8" y1="334.434" x2="780.8" y2="334.434"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="682.8" y1="410.934" x2="777.8" y2="410.934"/>
+  <g>
+    <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" d="M 684.5,342.584 A 30.4704,30.4704 0 0 0 676.673,403.011"/>
+    <polygon style="fill: #0000ff" points="679.632,403.321 675.608,405.273 676.632,403.285 675.656,401.273 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" points="679.632,403.321 675.608,405.273 676.632,403.285 675.656,401.273 "/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="694.75" y="367" width="60.2083" height="10.5"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" x="694.75" y="367" width="60.2083" height="10.5"/>
+  </g>
+  <text font-size="5.64444" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="653" y="323.334">
+    <tspan x="653" y="323.334">4 GiB </tspan>
+  </text>
+  <text font-size="7.90222" style="fill: #0000ff;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="707.958" y="348.25">
+    <tspan x="707.958" y="348.25">FIT Ptr</tspan>
+  </text>
+  <text font-size="7.90222" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="692.934" y="330.55">
+    <tspan x="692.934" y="330.55">IA32 reset vec</tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="694.684" y="415.25" width="60.2083" height="41.5333"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" x="694.684" y="415.25" width="60.2083" height="41.5333"/>
+  </g>
+  <g>
+    <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" d="M 654.458,327 A 65.5176,65.5176 0 0 0 675.175,449.031"/>
+    <polygon style="fill: #ff0000" points="678.138,449.469 673.953,451.045 675.154,449.159 674.366,447.066 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" points="678.138,449.469 673.953,451.045 675.154,449.159 674.366,447.066 "/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="694.934" y="462.5" width="60.2083" height="28.7474"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" x="694.934" y="462.5" width="60.2083" height="28.7474"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="695.434" y="518.45" width="60.2083" height="12.134"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #00ff00" x="695.434" y="518.45" width="60.2083" height="12.134"/>
+  </g>
+  <text font-size="6.77333" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="708.208" y="479.25">
+    <tspan x="708.208" y="479.25">BIOS ACM</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="707.184" y="432.25">
+    <tspan x="707.184" y="432.25">BOOTBLOCK</tspan>
+    <tspan x="707.184" y="440.717">CODE</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #00ff00;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="714.934" y="527">
+    <tspan x="714.934" y="527">uCode</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" x1="655.186" y1="327.12" x2="687.728" y2="326.952"/>
+  <g>
+    <rect style="fill: #ffffff" x="694.684" y="377.45" width="60.2083" height="10.5"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" x="694.684" y="377.45" width="60.2083" height="10.5"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="694.75" y="387.95" width="60.2083" height="10.5"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" x="694.75" y="387.95" width="60.2083" height="10.5"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="694.684" y="398.4" width="60.2083" height="10.5"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #0000ff" x="694.684" y="398.4" width="60.2083" height="10.5"/>
+  </g>
+  <g>
+    <rect style="fill: #ffffff" x="691.018" y="588.75" width="68.5" height="4.25"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="691.018" y="588.75" width="68.5" height="4.25"/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="689.334" y1="590.834" x2="689.018" y2="509.25"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="683.092" y1="493.9" x2="778.092" y2="493.9"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="682.592" y1="459.4" x2="777.592" y2="459.4"/>
+  <g>
+    <rect style="fill: #ffffff" x="695.776" y="533.91" width="60.2083" height="12.134"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #00ff00" x="695.776" y="533.91" width="60.2083" height="12.134"/>
+  </g>
+  <text font-size="6.77333" style="fill: #00ff00;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="714.026" y="542.21">
+    <tspan x="714.026" y="542.21">uCode</tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="695.276" y="497.072" width="60.2083" height="15.675"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" x="695.276" y="497.072" width="60.2083" height="15.675"/>
+  </g>
+  <text font-size="6.77333" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="715.276" y="546.122">
+    <tspan x="715.276" y="546.122"></tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="695.776" y="551.072" width="60.2083" height="15.3485"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ff0000" x="695.776" y="551.072" width="60.2083" height="15.3485"/>
+  </g>
+  <text font-size="6.77333" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="705.1" y="506.148">
+    <tspan x="705.1" y="506.148">verstage</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #ff0000;text-anchor:start;font-family:monospace;font-style:normal;font-weight:normal" x="719.35" y="561.32">
+    <tspan x="719.35" y="561.32">FSP</tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="682.1" y1="515.408" x2="777.1" y2="515.408"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="682.85" y1="548.738" x2="777.85" y2="548.738"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.75" y1="322.584" x2="789.75" y2="458.408"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.5" y1="457.908" x2="783" y2="457.908"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.6" y1="322.508" x2="783.1" y2="322.508"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.75" y1="493.226" x2="790.1" y2="513.834"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.85" y1="513.334" x2="783.35" y2="513.334"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="790.2" y1="493.934" x2="783.7" y2="493.934"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.65" y1="549.094" x2="790" y2="569.7"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="789.75" y1="569.2" x2="783.25" y2="569.2"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" x1="790.1" y1="549.8" x2="783.6" y2="549.8"/>
+  <g>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 2; stroke: #ff8484" d="M 753.708,392.75 A 49.3538,49.3538 0 0 0 783.042,393.053"/>
+    <polygon style="fill: #ffffff" points="784.252,395.824 787.724,391.442 782.136,391.293 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" points="784.252,395.824 787.724,391.442 782.136,391.293 "/>
+  </g>
+  <g>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 2; stroke: #ff8484" d="M 796.338,500.253 A 63.4678,63.4678 0 0 0 754.892,382.7"/>
+    <polygon style="fill: #ffffff" points="795.536,498.321 791.972,502.627 797.555,502.895 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" points="795.536,498.321 791.972,502.627 797.555,502.895 "/>
+  </g>
+  <g>
+    <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 2; stroke: #ff8484" d="M 795.51,554.953 A 86.6963,86.6963 0 0 0 754.892,403.65"/>
+    <polygon style="fill: #ffffff" points="794.249,553.15 791.641,558.095 797.162,557.214 "/>
+    <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff8484" points="794.249,553.15 791.641,558.095 797.162,557.214 "/>
+  </g>
+  <text font-size="12.8" style="fill: #ff8484;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="792.75" y="458.584">
+    <tspan x="792.75" y="458.584">IBB</tspan>
+  </text>
+  <text font-size="12.8" style="fill: #ff8484;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="792" y="516.808">
+    <tspan x="792" y="516.808">IBB</tspan>
+  </text>
+  <text font-size="12.8" style="fill: #ff8484;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="791.75" y="571.384">
+    <tspan x="791.75" y="571.384">IBB</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #0000ff;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="713.25" y="394.834">
+    <tspan x="713.25" y="394.834">type 7</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #0000ff;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="713" y="384.958">
+    <tspan x="713" y="384.958">type 7</tspan>
+  </text>
+  <text font-size="6.77333" style="fill: #0000ff;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="713.25" y="405.458">
+    <tspan x="713.25" y="405.458">type 7</tspan>
+  </text>
+  <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 689.334 590.834 C 714.206,590.834 736.628,598.912 761.5,598.912"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="761.71" y1="590.834" x2="761.5" y2="599.412"/>
+</svg>
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