[Skiboot] [PATCH 03/15] doc: Add initial secure and trusted boot documentation

[Claudio Carvalho]

This adds an initial documentation for the secure and trusted boot
implementation in skiboot.

Signed-off-by: Claudio Carvalho <cclaudio at linux.vnet.ibm.com>
---
 doc/stb.txt | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 doc/stb.txt

diff --git a/doc/stb.txt b/doc/stb.txt
new file mode 100644
index 0000000..3905a89
--- /dev/null
+++ b/doc/stb.txt
@@ -0,0 +1,147 @@
+Overview
+========
+
+Secure boot seeks to protect the system integrity from execution of malicious
+code during the boot. The authenticity and integrity of every code is verified
+by the predecessor code before it is executed. If the verification fails, the
+boot process is aborted.
+
+Trusted boot makes no enforcement, instead it creates artifacts during the
+system boot to prove that a particular chain of events have happened in the
+boot. Interested parties can subsequently assess the artifacts to check whether
+or not only trusted events happened and then make security decisions. These
+artifacts are a log of measurements and the digests saved in the TPM PCRs.
+Platform Configuration Registers (PCRs) are shielded registers of the Trusted
+Platform Module (TPM).
+
+Trusted boot measures and maintains in a Event Log a record of all boot
+events that may affect the security state of the platform. A measurement is
+calculated by hashing the data of the referred event. When a new measurement is
+added to the Event Log, the same measurement is also sent to the TPM, which
+performs an extend operation to incrementally update the existing digest saved
+in a PCR.
+
+PCR extend is an operation that uses a hash function to combine the new
+measurement with the existing digest saved in the PCR. Basically, it
+concatenates the existing PCR value with the received measurement, and then
+save the hash of this string in the PCR.
+
+The TPM may maintain multiple banks of PCR, where a PCR bank is a collection of
+PCRs that are extended with the same hash algorithm. TPM 2.0 has a sha1 bank
+and a sha256 bank with 24 PCRs each.
+
+As the system boot is complete, each non-zero PCR value represents one or more
+events measured during the boot in a chronological order. Interested parties
+can make inferences about the system's state by using an attestation tool to
+remotely compare the PCR values of a TPM against known good values, and also
+identify unexpected events by replaying the Event Log against known good Event
+Log entries.
+
+
+Implementation in skiboot
+=========================
+
+Secure boot: verify and enforce.
+Trusted boot: measure and record.
+
+Libstb implements an API for secure and trusted boot, which is used to verify
+and measure resources retrieved from PNOR. The libstb interface is documented
+in 'libstb/stb.h'
+
+Example of usage for libstb:
+
+	stb_init();
+		sb_verify(RESOURCE_ID_KERNEL, 0, buf);
+		tb_measure(RESOURCE_ID_KERNEL, 0, buf, len);
+		sb_verify(RESOURCE_ID_CAPP, 0, buf);
+		tb_measure(RESOURCE_ID_CAPP, 0, buf, len);
+		...
+	stb_final();
+
+The first step initializes libstb. stb_init() reads the secure mode and
+trusted mode flags from the device tree and loads the ROM and TPM drivers
+accordingly.
+
+Once libstb is initialized in the platform, sb_verify and tb_measure can be
+called to verify and measure resources, respectively. 
+
+Finally, before the control is passed to the petitboot kernel, stb_final must
+be called in order to add marks in the TPM device and the event log. Basically,
+it records an EV_SEPARATOR event in the event log for PCR[0-7], extend the
+sha1 and sha256 digests of 0xFFFFFFFF in PCR[0-7], and deallocates the memory
+allocated for secure and trusted boot.
+
+
+Verifying a resource
+--------------------
+
+In secure boot we verify and enforce. This functionality is provided by sb_verify,
+which verifies the integrity and authenticity of a resource downloaded from PNOR
+if secure mode is on. The verification itself is done by the verification code
+flashed in the secure ROM at manufacture time, but copied to memory at boot time.
+stb_init loads a compatible ROM code driver to interact with the verification
+code.
+
+In general terms, the verification of a resource will pass only if the following
+conditions are satisfied, otherwise the boot process is aborted.
+
+	- secure boot headers are properly built and attached to the resource.
+	  The secure boot headers have keys, hashes and signatures, and the
+          secure ROM code verifies each of these fields when sb_verify is
+          called.
+	  The secure boot headers and the resource are also collectively
+          referred to as secure boot container, or just container. The secure
+	  boot headers is the container header and the resource is the
+	  container payload.
+
+	- the public hardware keys of the container header matches with the
+	  hw-key-hash read from the device tree. The way that secure boot is
+	  designed, this assertion ensures that only resources signed by the
+	  owner of the hw-key-hash will pass the verification.
+	  The hw-key-hash is a hash of three hardware public keys flashed in
+	  SEEPROM at manufacture time and written to the device tree at boot
+	  time.
+
+Please refer to 'doc/device-tree/ibm,secureboot.txt' for a brief explanation
+about the device tree properties mentioned in this section.
+
+
+Measuring a resource
+--------------------
+
+In trusted boot we measure and record. This functionality is provided by
+tb_measure, which measure and record for a resource downloaded from PNOR if
+trusted mode is on. tb_measure returns an error if the resource is not
+included in the resource_map whitelist. The resource_map indicates in what
+PCR the measurement of the resource must be recorded and extended.
+All resources consumed by skiboot should be added to resource_map whitelist.
+
+Steps performed by tb_measure:
+
+1. measure the resource
+2. record an event in the event log for the mapped PCR
+3. extend the measurements in the mapped PCR
+
+In the first step, we measure the resource for each PCR bank: sha1 and sha256.
+If secure mode is on and the resource is a container, we just get the sha512 
+hash of the resource from the container header (sw-payload-hash field) and
+truncate it for both PCR banks. Otherwise, we call the ROM code to calculate
+the sha512 hash of the resource at boot time and then we truncate the hash
+for both PCR banks.
+
+In the second step, we call the eventLogMgr API to generate an event with
+both the sha1 and sha256 measurements and record the new event in the
+event log for the mapped PCR. stb_init initializes the event log from the
+device tree.
+
+Finally, in the third step we call a TCG Software Stack (TSS) implementation
+to extend the measurements in the mapped PCR for both banks. That is done in
+a single operation sent to the TPM. The first 20 bytes of the sha512 hash is
+extended in the sha1 bank and the first 32 bytes of the sha512 hash is
+extended in the sha256 bank. stb_init loads a compatible driver for TPM device.
+
+Both TSS and eventLogMgr are hostboot implementations, but their source code
+are shared with skiboot.
+
+Please refer to 'doc/device-tree/tpm.txt' for a brief explanation about the
+device tree properties mentioned in this section.
-- 
1.9.1