[Skiboot] [PATCH 18/19] doc: update libstb documentation with POWER9 changes
Claudio Carvalho
cclaudio at linux.vnet.ibm.com
Sun Nov 12 04:28:41 AEDT 2017
In POWER9, the libstb interface has changed due mainly to the changes:
- early init of the Container-Verification-Code (CVC) during the HDAT parsing
- versioning of each CVC service
This extends the libstb documentation adding sections such as "Signing
Firmware Code", and also updates it with the interface changes made in
POWER9.
This also cleans up the doc/device-tree/ibm,secureboot.rst
documentation.
Signed-off-by: Claudio Carvalho <cclaudio at linux.vnet.ibm.com>
---
doc/device-tree/ibm,secureboot.rst | 42 ++----
doc/device-tree/tpm.rst | 6 +-
doc/stb.rst | 299 ++++++++++++++++++-------------------
3 files changed, 165 insertions(+), 182 deletions(-)
diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst
index 948c7e0..55dc032 100644
--- a/doc/device-tree/ibm,secureboot.rst
+++ b/doc/device-tree/ibm,secureboot.rst
@@ -3,54 +3,38 @@
ibm,secureboot
==============
-Secure boot and trusted boot relies on a code stored in the secure ROM at
-manufacture time to verify and measure other codes before they are executed.
-This ROM code is also referred to as ROM verification code.
-
-On POWER8, the presence of the ROM code is announced to skiboot (by Hostboot)
-by the ``ibm,secureboot`` device tree node.
-
-If the system is booting up in secure mode, the ROM code is called for secure
-boot to verify the integrity and authenticity of an image before it is executed.
-
-If the system is booting up in trusted mode, the ROM code is called for trusted
-boot to calculate the SHA512 hash of an image only if the image is not a secure boot
-container or the system is not booting up in secure mode.
-
-For further information about secure boot and trusted boot please refer to
-:ref:`stb-overview`.
-
+The ``ìbm,secureboot`` node provides secure boot and trusted boot information
+up to the target OS. Further information can be found in :ref:`stb-overview`.
Required properties
-------------------
.. code-block:: none
- compatible: ibm,secureboot version. It is related to the ROM code version.
-
- hash-algo: hash algorithm used for the hw-key-hash. Aspects such as the size
- of the hw-key-hash can be infered from this property.
+ compatible: Should be "ibm,secureboot-v1"
+
+ secure-enabled: this property exists when the firmware stack is booting
+ in secure mode (hardware secure boot jumper asserted).
- secure-enabled: this property exists if the system is booting in secure mode.
+ trusted-enabled: this property exists when the firmware stack is booting
+ in trusted mode.
- trusted-enabled: this property exists if the system is booting in trusted mode.
+ hw-key-hash: hash of the three hardware public keys trusted by the
+ platformw owner. This is used to verify if a firmware
+ code is signed with trusted keys.
- hw-key-hash: hash of three concatenated hardware public key. This is required
- by the ROM code to verify images.
+ hash-algo: indicate the hw-key-hash size
Example
-------
-For the first version ``ibm,secureboot-v1``, the ROM code expects the *hw-key-hash*
-to be a SHA512 hash.
-
.. code-block:: dts
ibm,secureboot {
compatible = "ibm,secureboot-v1";
- hash-algo = "sha512";
secure-enabled;
trusted-enabled;
+ hash-algo = "sha512"
hw-key-hash = <0x40d487ff 0x7380ed6a 0xd54775d5 0x795fea0d 0xe2f541fe
0xa9db06b8 0x466a42a3 0x20e65f75 0xb4866546 0x17d907
0x515dc2a5 0xf9fc5095 0x4d6ee0c9 0xb67d219d 0xfb708535
diff --git a/doc/device-tree/tpm.rst b/doc/device-tree/tpm.rst
index d4e7667..a8e67bc 100644
--- a/doc/device-tree/tpm.rst
+++ b/doc/device-tree/tpm.rst
@@ -9,12 +9,12 @@ event log information.
Required properties
-------------------
-All these properties are added by hostboot and consumed by skiboot and the
-linux kernel (tpm and vtpm codes)
+All these properties are consumed by skiboot and the linux kernel (tpm and
+vtpm codes)
::
- compatible : manufacturer,model
+ compatible : should have "nuvoton,npct650"
linux,sml-base: 64-bit base address of the reserved memory allocated for firmware event log.
sml stands for shared memory log.
diff --git a/doc/stb.rst b/doc/stb.rst
index 2004af8..5b3a8e1 100644
--- a/doc/stb.rst
+++ b/doc/stb.rst
@@ -1,42 +1,157 @@
.. _stb-overview:
-================================
-Secure and Trusted 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
+Secure and Trusted Boot Library (LibSTB) Documentation
+======================================================
+
+*LibSTB* provides APIs to support Secure Boot and Trusted Boot in skiboot.
+
+``Secure Boot: verify and enforce.``
+ When the system is booting in secure mode, Secure Boot MUST ensure that
+ only trusted code is executed during system boot by verifying if the
+ code is signed with trusted keys and halting the system boot if the
+ verification fails.
+
+``Trusted Boot: measure and record.``
+ When the system is booting in trusted mode, Trusted Boot MUST create
+ 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.
+
+In order to support Secure and Trusted Boot, the flash driver calls libSTB to
+verify and measure the code it fetches from PNOR.
+
+LibSTB is initialized by calling *stb_init()*, see ``libstb/stb.h``.
+
+Secure Boot
+-----------
+
+``Requirements:``
+ #. CVC-verify service to verify signed firmware code.
+
+The Secure Boot API is quite simple, see ``libstb/secureboot.h``.
+
+The flash driver calls ``secureboot_verify()`` to verify if the fetched firmware
+blob is properly signed with keys trusted by the platform owner. This
+verification is performed only when the system is booting in secure mode. If
+the verification fails, it enforces a halt of the system boot.
+
+The verification itself is performed by the :ref:`container-verification-code`,
+precisely the *CVC-verify* service, which requires both the fetched code and the
+hardware key hash trusted by the platform owner.
+
+The secure mode status, hardware key hash and hardware key hash size
+information is found in the device tree, see
+:ref:`doc/device-tree/ibm,secureboot.rst <device-tree/ibm,secureboot>`.
+
+Signing Firmware Code
+^^^^^^^^^^^^^^^^^^^^^
+
+Fimware code is signed using the ``sb-signing-utils`` utilities by running it
+standalone or just calling op-build. The latter will automatically sign the
+various firmware components that comprise the PNOR image if SECUREBOOT is
+enabled for the platform.
+
+The signing utilities also allow signing firmware code using published hardware
+keys (a.k.a. imprint keys, only for development) or production hardware keys,
+see `sb-signing-utils`_.
+
+The hardware keys are the root keys. The signing tool uses three hardware keys
+to sign up to three firmware keys, which are then used to sign the firmware
+code. The resulting signed firmware code is then assembled following the secure
+boot container format. All the information required to verify the signatures is
+placed in the first 4K reserved for the container header (e.g. public keys,
+hashes and signatures). The firmware code itself is placed in the container
+payload.
+
+.. _sb-signing-utils: https://github.com/open-power/sb-signing-utils
+
+.. _container-verification-code:
+
+Container Verification Code
+---------------------------
+
+The *Container Verification Code* (a.k.a. ROM code) is stored in a secure
+memory region and it provides basic Secure and Trusted Boot services for the
+entire firmware stack. Its presence is announced to skiboot by the
+*ibm,secureboot* device tree node, see `doc/device-tree/ibm,secureboot.rst
+<device-tree/ibm,secureboot>`.
+
+LibSTB uses function wrappers to call into each CVC service, see
+``libstb/cvc.h``.
+
+CVC-verify Service
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: c
+
+ int call_cvc_verify(void *buf, size_t size, const void *hw_key_hash,
+ size_t hw_key_hash_size, uint64_t *log)
+
+This function wrapper calls into the *CVC-verify* service, which verifies if the
+firmware code provided in ``@buf`` is properly signed with the keys trusted by
+the platform owner. Its parameters are documented in ``libstb/cvc.h``.
+
+Authenticity is one for the first checks performed by the CVC-verify
+service. It checks if the provided hardware key hash matches the hash of the
+three hardware public keys found in the container header. Afterwards, the
+service verifies the remaining fields of the container header.
+
+``@log`` is optional. If the verification fails, the caller can interpret
+it to find out what checks has failed.
+
+Enforcement is caller's responsibility.
+
+CVC-sha512 Service
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: c
+
+ int call_cvc_sha512(const uint8_t *data, size_t data_len, uint8_t *digest,
+ size_t digest_size)
+
+This function wrapper calls into the *CVC-sha512* service, which calculates the
+sha512 hash of what is provided in @data. Its parameters are documented in
+``libstb/cvc.h``.
+
+Trusted Boot
+------------
+
+``Requirements:``
+ #. TPM device and TPM driver. See devices supported in
+ :ref:`doc/device-tree/tpm.rst <device-tree/tpm>`.
+ #. TCG Software Stack (TSS) to send commands to the TPM device.
+ #. Firmware Event Log driver to add new events to the log. Event log
+ address and size information is found in the device tree, see
+ :ref:`doc/device-tree/tpm.rst <device-tree/tpm>`.
+ #. CVC-sha512 service to calculate the sha512 hash of the data that
+ will be measured.
+
+The Trusted Boot API is quite simple, see ``libstb/trustedboot.h``.
+
+The flash driver calls ``trustedboot_measure()`` to measure the firmware code
+fetched from PNOR and also record its measurement in two places. This is
+performed only when the system is booting in trusted mode (information found in
+the device tree, see :ref:`doc/device-tree/ibm,secureboot.rst <device-tree/ibm,secureboot>`).
+
+Once the firmware code is measured by calling the *CVC-sha512* service, its
+measurement is first recorded in a TPM PCR statically defined for each event.
+In order to record it, the skiboot TCG Software Stack (TSS) API is called to
+extend the measurement into the PCR number of both the sha1 and sha256 banks.
+The skiboot TSS is a light TSS implementation and its source code is shared
+between hostboot and skiboot, see ``libstb/tss/trustedbootCmds.H``.
+
+PCR extend is an TPM 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.
+records the hash of this new 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.
+The measurement is also recorded in the event log. The ``TpmLogMgr_addEvent()``
+function is called to add the measurement to the log, see
+``libstb/tss/tpmLogMgr.H``.
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
@@ -44,119 +159,3 @@ 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.
--
2.7.4
More information about the Skiboot
mailing list