doc/stb.rst

.. _stb-overview:

===============================
Secure and Truted Boot Overview
===============================

Just as a quick reference::

  Secure boot:  verify and enforce.
  Trusted boot: measure and record.

Secure boot seeks to protect system integrity from execution of malicious
code during boot. The authenticity and integrity of every code is verified
by its predecessor code before it is executed. If the verification fails, the
boot process is aborted.

Trusted boot does not perform enforcement. Instead it creates artifacts during
system boot to prove that a particular chain of events have happened during
boot. Interested parties can subsequently assess the artifacts to check whether
or not only trusted events happened and then make security decisions. These
artifacts comprise a log of measurements and the digests extended into the TPM PCRs.
Platform Configuration Registers (PCRs) are registers in the Trusted Platform
Module (TPM) that are shielded from direct access by the CPU.

Trusted boot measures and maintains in an 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 a given 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 stored
in a PCR.

PCR extend is an operation that uses a hash function to combine a new
measurement with the existing digest saved in the PCR. Basically, it
concatenates the existing PCR value with the received measurement, and then
stores the hash of this string in the PCR.

The TPM may maintain multiple banks of PCRs, 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.

When the system boot is complete, each non-zero PCR value represents one or more
events measured during the boot in 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
-------------------------

Libstb implements an API for secure and trusted boot, which is used to verify
and measure images retrieved from PNOR. The libstb interface is documented
in ``libstb/stb.h``

The example below shows how libstb can be used to add secure and trusted
boot support for a platform:

::

    stb_init();
        start_preload_resource(RESOURCE_ID_CAPP, 0, capp_ucode_info.lid, &capp_ucode_info.size);
            sb_verify(id, buf, len);
            tb_measure(id, buf, len);
        start_preload_resource(RESOURCE_ID_KERNEL, 0, KERNEL_LOAD_BASE, &kernel_size);
            sb_verify(id, buf, len);
            tb_measure(id, buf, len);
    stb_final();

First, ``stb_init()`` must be called to initialize libstb. Basically, it reads both
secure mode and trusted mode flags and loads drivers accordingly. In P8, secure
mode and trusted mode are read from the *ibm,secureboot* device tree node (see
:ref:`device-tree/ibm,secureboot`).

If either secure mode or trusted mode is on, ``stb_init()`` loads a driver (romcode
driver) to access the verification and SHA512 functions provided by the code
stored in the secure ROM at manufacture time. Both secure boot and trusted boot
depends on the romcode driver to access the ROM code. If trusted mode is on,
``stb_init()`` loads a TPM device driver compatible with the tpm device tree node
and also initializes the existing event log in skiboot. For device tree bindings
for the TPM, see :ref:`device-tree/tpm`.

Once libstb is initialized in the platform, ``sb_verify()`` and ``tb_measure()`` can
used as shown in the example above to respectively verify and measure images
retrieved from PNOR. If a platform claims secure and trusted boot support, then
``sb_verify()`` and ``tb_measure()`` is called for all images retrieved from PNOR. 

``sb_verify()`` and ``tb_measure()`` do nothing if libstb is not initialized in the
platform since both secure mode and trusted mode are off by default.

Finally, ``stb_final()`` must be called when no more images need to be retrieved
from PNOR in order to indicate that secure boot and trusted boot have completed
in skiboot. When stb_final() is called, basically it records eight *EV_SEPARATOR*
events in the event log (one for each PCR through 0 to 7) and extends the PCR
through 0 to 7 of both SHA1 and SHA256 PCR banks with the digest of *0xFFFFFFFF*.
Additionally, ``stb_final()`` also frees resources allocated for secure boot and
trusted boot.


Verifying an image
~~~~~~~~~~~~~~~~~~

If secure mode is on, ``sb_verify()`` verifies the integrity and authenticity of an
image by calling the ``ROM_verify()`` function from the ROM code via romcode driver. In
general terms, this verification will pass only if the following conditions are
satisfied. Otherwise the boot process is aborted.

1. Secure boot header is properly built and attached to the image.  When
   ``sb_verify()`` is called, the ROM code verifies all the secure boot header
   fields, including the keys, hashes and signatures.  The secure boot header
   and the image are also collectively referred to as secure boot container, or
   just container. As the secure boot header is the container header and the
   image is the container payload.

2. The public hardware keys of the container header match with the hw-key-hash
   read from the device tree. The way that secure boot is designed, this
   assertion ensures that only images 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 stored in *SEEPROM* at manufacture time and written to the device
   tree at boot time.


Measuring an image
~~~~~~~~~~~~~~~~~~

``tb_measure()`` measures an image retrieved from PNOR if trusted mode is on, but
only if the provided image is included in the *resource_map* whitelist. This
whitelist defines for each expected image to what PCR the measurement must be
recorded and extended. ``tb_measure()`` returns an error if the provided image is
not included in the *resource_map* whitelist.

For the sake of simplicity we say that ``tb_measure()`` measures an image, but
calculating the digest of a given image is just one of the steps performed by
``tb_measure()``.

Steps performed by ``tb_measure()`` if trusted mode is on:

1. Measure the provided image for each PCR bank: SHA1 and SHA256. If secure
   mode is on and the image is a container, parse the container header to get
   the SHA512 hash of the container payload (*sw-payload-hash* field). Otherwise,
   call the ROM code via romcode driver to calculate the SHA512 hash of the
   image at boot time. In both cases, the SHA512 hash is truncated to match the
   size required by each PCR bank: SHA1 bank PCRs are 20 bytes and SHA256 bank
   PCRs are 32 bytes.

2. Record a new event in the event log for the mapped PCR. Call the tpmLogMgr
   API to generate a new event and record it in the event log. The new event is
   generated for the mapped PCR and it also contains a digest list with both
   SHA1 and SHA256 measurements obtained in step 1.

3. Extend the measurements into the mapped PCR. Call the TCG Software Stack
   (TSS) API to extend both measurements obtained in step 1 into the mapped PCR
   number. The SHA1 measurement is extended to the SHA1 PCR bank and the SHA256
   measurement is extended to the SHA256 PCR bank. However, they are extended
   to the same PCR number on each bank.
   Since this TSS implementation supports multibank, it does the marshalling of
   both SHA1 and SHA256 measurements into a single TPM extend command and then
   it sends the command to the TPM device via TPM device driver.

Both TSS and tpmLogMgr APIs are implemented by hostboot, but their source code
are added to skiboot. The TSS and tpmLogMgr interfaces are defined in
``libstb/tss/trustedbootCmds.H`` and ``libstb/tss/tpmLogMgr.H``, respectively.