diff options
| -rw-r--r-- | Documentation/security/index.md | 6 | ||||
| -rw-r--r-- | Documentation/security/intel/acm.md | 57 | ||||
| -rw-r--r-- | Documentation/security/intel/fit_ibb.dia | bin | 0 -> 3706 bytes | |||
| -rw-r--r-- | Documentation/security/intel/fit_ibb.svg | 153 | ||||
| -rw-r--r-- | Documentation/security/intel/txt.md | 117 | ||||
| -rw-r--r-- | Documentation/security/intel/txt_ibb.md | 39 |
6 files changed, 372 insertions, 0 deletions
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 Binary files differnew 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 |
