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

[Balbir Singh]

On 11/08/16 15:23, Claudio Carvalho wrote:
> 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
                              ^^^ why? Is this standard practice?

> +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.
> +

Good writeup, I know its obvious, does the design limit Secure Boot/Trusted Boot
to one key at a time? Can I have several keys marked as secure?

> +
> +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.

What are 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.
> +

The interaction between sha1/sha2 and sha512 is not very clear


> +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.
> 


Balbir Singh