<p>Philipp Deppenwiese has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/26925">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation: Add Trusted Computing documentation<br><br>* Introduce security section.<br>* Add Trusted Computing Technology doc.<br><br>Change-Id: I8d49a113c77c08c0c703791a160704ae57e3c3f7<br>Signed-off-by: Philipp Deppenwiese <zaolin@das-labor.org><br>---<br>M Documentation/index.md<br>A Documentation/security/security.md<br>A Documentation/security/trusted-computing/code-structure.png<br>A Documentation/security/trusted-computing/index.md<br>A Documentation/security/trusted-computing/normal-tpm-boot-flow.png<br>A Documentation/security/trusted-computing/vboot-tpm-boot-flow.png<br>6 files changed, 148 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/25/26925/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/index.md b/Documentation/index.md</span><br><span>index 4ec4550..3b01558 100644</span><br><span>--- a/Documentation/index.md</span><br><span>+++ b/Documentation/index.md</span><br><span>@@ -9,6 +9,7 @@</span><br><span> </span><br><span> * [Getting Started](getting_started/index.md)</span><br><span> * [Rookie Guide](lessons/index.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Security](security/index.md)</span><br><span> * [Timestamps](timestamp.md)</span><br><span> * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)</span><br><span> * [ABI data consumption](abi-data-consumption.md)</span><br><span>diff --git a/Documentation/security/security.md b/Documentation/security/security.md</span><br><span>new file mode 100644</span><br><span>index 0000000..b960dbb</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/security/security.md</span><br><span>@@ -0,0 +1,10 @@</span><br><span style="color: hsl(120, 100%, 40%);">+.. toctree::</span><br><span style="color: hsl(120, 100%, 40%);">+ :maxdepth: 2</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# Security Section</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The security describes existing technologies which are shipped with coreboot.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* [Trusted Computing Technology](trusted-computing/index.md)</span><br><span>\ No newline at end of file</span><br><span>diff --git a/Documentation/security/trusted-computing/code-structure.png b/Documentation/security/trusted-computing/code-structure.png</span><br><span>new file mode 100644</span><br><span>index 0000000..6e28de5</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/security/trusted-computing/code-structure.png</span><br><span>Binary files differ</span><br><span>diff --git a/Documentation/security/trusted-computing/index.md b/Documentation/security/trusted-computing/index.md</span><br><span>new file mode 100644</span><br><span>index 0000000..d59217d</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/security/trusted-computing/index.md</span><br><span>@@ -0,0 +1,137 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Trusted Computing Technology</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot offers trusted computing support for the TCG specification 1.1, 1.2 and 2.0. Bus protocols like I2C, SPI and PC80 are supported by default. For more information please consult the [TCG](https://trustedcomputinggroup.org/).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Integration</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot integrates multiple layers of the TCG specification:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### TIS</span><br><span style="color: hsl(120, 100%, 40%);">+The TPM Interface Service is the driver layer communicating directly to the TPM through different bus implementations.</span><br><span style="color: hsl(120, 100%, 40%);">+Those implementations can be found under:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+src/drivers/pc80/tpm/</span><br><span style="color: hsl(120, 100%, 40%);">+src/drivers/i2c/tpm/</span><br><span style="color: hsl(120, 100%, 40%);">+src/drivers/spi/tpm/</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### TSS</span><br><span style="color: hsl(120, 100%, 40%);">+The TPM Software Stack is the implementation of the TPM communication protocol and commands which can be used to execute task on a TPM. Évery TPM specification has its own functionality which needs to be implemented standalone.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Some vendors like Google implement their own TPM specification additions like CR50.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Implementation can be found under:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+src/security/tpm/tss</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### TSPI</span><br><span style="color: hsl(120, 100%, 40%);">+The TPM Service Provider Interface is the high level interface of a TPM and offers more complex functions which should be used as generic interface inside coreboot. The TSPI implements functions of the TSS. Interface functions can be found inside the tspi.h:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```c</span><br><span style="color: hsl(120, 100%, 40%);">+/*</span><br><span style="color: hsl(120, 100%, 40%);">+ * This file is part of the coreboot project.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Copyright (c) 2013 The Chromium OS Authors. All rights reserved.</span><br><span style="color: hsl(120, 100%, 40%);">+ * Copyright 2018 Facebook Inc.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This program is free software; you can redistribute it and/or modify</span><br><span style="color: hsl(120, 100%, 40%);">+ * it under the terms of the GNU General Public License as published by</span><br><span style="color: hsl(120, 100%, 40%);">+ * the Free Software Foundation; version 2 of the License.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This program is distributed in the hope that it will be useful,</span><br><span style="color: hsl(120, 100%, 40%);">+ * but WITHOUT ANY WARRANTY; without even the implied warranty of</span><br><span style="color: hsl(120, 100%, 40%);">+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the</span><br><span style="color: hsl(120, 100%, 40%);">+ * GNU General Public License for more details.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#ifndef TSPI_H_</span><br><span style="color: hsl(120, 100%, 40%);">+#define TSPI_H_</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include <security/tpm/tss.h></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/**</span><br><span style="color: hsl(120, 100%, 40%);">+ * Ask vboot for a digest and extend a TPM PCR with it.</span><br><span style="color: hsl(120, 100%, 40%);">+ * @param pcr sets the pcr index</span><br><span style="color: hsl(120, 100%, 40%);">+ * @param digest sets the hash to extend into the tpm</span><br><span style="color: hsl(120, 100%, 40%);">+ * @param out_digest get extended hash</span><br><span style="color: hsl(120, 100%, 40%);">+ * @return TPM_SUCCESS on success. If not a tpm error is returned</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+uint32_t tpm_extend_pcr(int pcr, uint8_t *digest, uint8_t *out_digest);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/**</span><br><span style="color: hsl(120, 100%, 40%);">+ * Issue a TPM_Clear and reenable/reactivate the TPM.</span><br><span style="color: hsl(120, 100%, 40%);">+ * @return TPM_SUCCESS on success. If not a tpm error is returned</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+uint32_t tpm_clear_and_reenable(void);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/**</span><br><span style="color: hsl(120, 100%, 40%);">+ * Start the TPM and establish the root of trust.</span><br><span style="color: hsl(120, 100%, 40%);">+ * @param s3flag tells the tpm setup if we wake up from a s3 state on x86</span><br><span style="color: hsl(120, 100%, 40%);">+ * @return TPM_SUCCESS on success. If not a tpm error is returned</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+uint32_t tpm_setup(int s3flag);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#endif /* TSPI_H_ */</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Implementation can be found under:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+src/security/tpm/tspi</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Normal boot flow</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The normal boot flow without measured boot and vboot is done by a TPM ramstage driver which is executed at the start of BS_DEV_INIT. The ramstage driver is automatically selected if there is no vboot enabled but the TPM support is compiled into the coreboot image.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Verified boot flow</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The vboot boot flow is different from the normal boot procedure. The TPM is initialized at the beginning of the verstage before the ramstage is loaded.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### TCPA ACPI log</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot does not use the official TCPA log because of limitations and specification issues. Therefore we offer two ACPI logs. The first is the standard log which is interfaced through ACPI buy bootloader and the OS. The second log is exposed via CBMEM and used by coreboot to report all measurements. To be compliant with the existing kernel TCPA ACPI log, cbmem prints the results in the same format.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Later a kernel driver may expose the log through /sys/firmware/ under linux.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Retrieval of the log is done by:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```bash</span><br><span style="color: hsl(120, 100%, 40%);">+util/cbmem/cbmem -L</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Mainboard support</span><br><span style="color: hsl(120, 100%, 40%);">+The basic TPM support can be easily activated by adding at least one select to the mainboard kconfig.</span><br><span style="color: hsl(120, 100%, 40%);">+First select one of the bus type driver:</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_I2C_TPM_ATMEL</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_I2C_TPM_CR50</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_I2C_TPM_GENERIC</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_SPI_TPM_CR50</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_LPC_TPM</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you added it to the config. You should already see a kconfig menu under Security -> Trusted Platform Module for selecting the TPM specification. This is useful for desktop and server boards which have a TPM header with multiple specification options.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you want to make this a hardcoded selection for laptops or embedded boards, just select one of the two kconfig options:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_TPM1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MAINBOARD_HAS_TPM2</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Ǹow you are done!</span><br><span>\ No newline at end of file</span><br><span>diff --git a/Documentation/security/trusted-computing/normal-tpm-boot-flow.png b/Documentation/security/trusted-computing/normal-tpm-boot-flow.png</span><br><span>new file mode 100644</span><br><span>index 0000000..20c9f31</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/security/trusted-computing/normal-tpm-boot-flow.png</span><br><span>Binary files differ</span><br><span>diff --git a/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png b/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png</span><br><span>new file mode 100644</span><br><span>index 0000000..1397af8</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png</span><br><span>Binary files differ</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/26925">change 26925</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/26925"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: I8d49a113c77c08c0c703791a160704ae57e3c3f7 </div>
<div style="display:none"> Gerrit-Change-Number: 26925 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Philipp Deppenwiese <zaolin.daisuki@gmail.com> </div>