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

[Stewart Smith]

Claudio Carvalho <cclaudio at linux.vnet.ibm.com> writes:
> 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

It would be great if this could be .rst rather than .txt so that it fits
in with the fancy new way of building pretty docs (i.e. "cd doc; make html")

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

What does this mean for any dependence on ordering of loading resources?
Do we have to be deterministic for a particular platform that KERNEL is
always loaded *before* CAPP ?

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

Is there any particularl reason why we do it this way rather than just
have our own implementation of the same algorithm?

Is there (public) source for what goes into the secure ROM?

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

So.... how would a user replace the keys?

I feel it's important to document how someone who's built their own
firmware would still boot securely/trusted.

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

*technically* it doesn't *have* to be PNOR, as we have the
load_resource() abstraction that just fetches things from $place

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

I think this'll be okay for now, it feels as though this should be part
of the core load_resource() code though... although I don't see a quick
obvious way to do that.

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

Do we also check the SHA512 hash matches with secure mode on? If not,
may want to specify why this is okay.

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

-- 
Stewart Smith
OPAL Architect, IBM.