[coreboot-gerrit] Change in coreboot[master]: Documentation: Add Trusted Computing documentation

Philipp Deppenwiese (Code Review) gerrit at coreboot.org
Wed Jun 6 18:28:12 CEST 2018 

Philipp Deppenwiese has uploaded this change for review. ( https://review.coreboot.org/26925


Change subject: Documentation: Add Trusted Computing documentation
......................................................................

Documentation: Add Trusted Computing documentation

* Introduce security section.
* Add Trusted Computing Technology doc.

Change-Id: I8d49a113c77c08c0c703791a160704ae57e3c3f7
Signed-off-by: Philipp Deppenwiese <zaolin at das-labor.org>
---
M Documentation/index.md
A Documentation/security/security.md
A Documentation/security/trusted-computing/code-structure.png
A Documentation/security/trusted-computing/index.md
A Documentation/security/trusted-computing/normal-tpm-boot-flow.png
A Documentation/security/trusted-computing/vboot-tpm-boot-flow.png
6 files changed, 148 insertions(+), 0 deletions(-)



  git pull ssh://review.coreboot.org:29418/coreboot refs/changes/25/26925/1

diff --git a/Documentation/index.md b/Documentation/index.md
index 4ec4550..3b01558 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -9,6 +9,7 @@
 
 * [Getting Started](getting_started/index.md)
 * [Rookie Guide](lessons/index.md)
+* [Security](security/index.md)
 * [Timestamps](timestamp.md)
 * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
 * [ABI data consumption](abi-data-consumption.md)
diff --git a/Documentation/security/security.md b/Documentation/security/security.md
new file mode 100644
index 0000000..b960dbb
--- /dev/null
+++ b/Documentation/security/security.md
@@ -0,0 +1,10 @@
+.. toctree::
+   :maxdepth: 2
+
+# Security Section
+
+The security describes existing technologies which are shipped with coreboot.
+
+Contents:
+
+* [Trusted Computing Technology](trusted-computing/index.md)
\ No newline at end of file
diff --git a/Documentation/security/trusted-computing/code-structure.png b/Documentation/security/trusted-computing/code-structure.png
new file mode 100644
index 0000000..6e28de5
--- /dev/null
+++ b/Documentation/security/trusted-computing/code-structure.png
Binary files differ
diff --git a/Documentation/security/trusted-computing/index.md b/Documentation/security/trusted-computing/index.md
new file mode 100644
index 0000000..d59217d
--- /dev/null
+++ b/Documentation/security/trusted-computing/index.md
@@ -0,0 +1,137 @@
+# Trusted Computing Technology
+
+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/).
+
+## Integration
+
+![integration](code-structure.png)
+
+coreboot integrates multiple layers of the TCG specification:
+
+### TIS
+The TPM Interface Service is the driver layer communicating directly to the TPM through different bus implementations.
+Those implementations can be found under:
+
+```
+src/drivers/pc80/tpm/
+src/drivers/i2c/tpm/
+src/drivers/spi/tpm/
+```
+
+### TSS
+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.
+
+Some vendors like Google implement their own TPM specification additions like CR50.
+
+Implementation can be found under:
+
+```
+src/security/tpm/tss
+```
+
+### TSPI
+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:
+
+```c
+/*
+ * This file is part of the coreboot project.
+ *
+ * Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
+ * Copyright 2018 Facebook Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#ifndef TSPI_H_
+#define TSPI_H_
+
+#include <security/tpm/tss.h>
+
+/**
+ * Ask vboot for a digest and extend a TPM PCR with it.
+ * @param pcr sets the pcr index
+ * @param digest sets the hash to extend into the tpm
+ * @param out_digest get extended hash
+ * @return TPM_SUCCESS on success. If not a tpm error is returned
+ */
+uint32_t tpm_extend_pcr(int pcr, uint8_t *digest, uint8_t *out_digest);
+
+/**
+ * Issue a TPM_Clear and reenable/reactivate the TPM.
+ * @return TPM_SUCCESS on success. If not a tpm error is returned
+ */
+uint32_t tpm_clear_and_reenable(void);
+
+/**
+ * Start the TPM and establish the root of trust.
+ * @param s3flag tells the tpm setup if we wake up from a s3 state on x86
+ * @return TPM_SUCCESS on success. If not a tpm error is returned
+ */
+uint32_t tpm_setup(int s3flag);
+
+#endif /* TSPI_H_ */
+```
+
+Implementation can be found under:
+
+```
+src/security/tpm/tspi
+```
+
+### Normal boot flow
+
+![](normal-tpm-boot-flow.png)
+
+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.
+
+### Verified boot flow
+
+![](vboot-tpm-boot-flow.png)
+
+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.
+
+### TCPA ACPI log
+
+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.
+
+Later a kernel driver may expose the log through /sys/firmware/ under linux.
+
+Retrieval of the log is done by:
+
+```bash
+util/cbmem/cbmem -L
+```
+
+## Mainboard support
+The basic TPM support can be easily activated by adding at least one select to the mainboard kconfig.
+First select one of the bus type driver:
+```
+MAINBOARD_HAS_I2C_TPM_ATMEL
+
+MAINBOARD_HAS_I2C_TPM_CR50
+
+MAINBOARD_HAS_I2C_TPM_GENERIC
+
+MAINBOARD_HAS_SPI_TPM_CR50
+
+MAINBOARD_HAS_LPC_TPM
+```
+
+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.
+
+If you want to make this a hardcoded selection for laptops or embedded boards, just select one of the two kconfig options:
+
+```
+MAINBOARD_HAS_TPM1
+
+MAINBOARD_HAS_TPM2
+```
+
+Ǹow you are done!
\ No newline at end of file
diff --git a/Documentation/security/trusted-computing/normal-tpm-boot-flow.png b/Documentation/security/trusted-computing/normal-tpm-boot-flow.png
new file mode 100644
index 0000000..20c9f31
--- /dev/null
+++ b/Documentation/security/trusted-computing/normal-tpm-boot-flow.png
Binary files differ
diff --git a/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png b/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png
new file mode 100644
index 0000000..1397af8
--- /dev/null
+++ b/Documentation/security/trusted-computing/vboot-tpm-boot-flow.png
Binary files differ

-- 
To view, visit https://review.coreboot.org/26925
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: I8d49a113c77c08c0c703791a160704ae57e3c3f7
Gerrit-Change-Number: 26925
Gerrit-PatchSet: 1
Gerrit-Owner: Philipp Deppenwiese <zaolin.daisuki at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180606/ad59b2a7/attachment-0001.html>

More information about the coreboot-gerrit mailing list