@@ -3,56 +3,57 @@
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.
+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`.
-On POWER8, the presence of the ROM code is announced to skiboot (by Hostboot)
-by the ``ibm,secureboot`` device tree node.
+Required properties
+-------------------
-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.
+.. code-block:: none
-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.
+ compatible: Either one of the following values:
-For further information about secure boot and trusted boot please refer to
-:ref:`stb-overview`.
+ ibm,secureboot-v1 : The container-verification-code
+ is stored in a secure ROM memory.
+ ibm,secureboot-v2 : The container-verification-code
+ is stored in a reserved memory.
+ It described by the ibm,cvc child
+ node.
-Required properties
--------------------
+ secure-enabled: this property exists when the firmware stack is booting
+ in secure mode (hardware secure boot jumper asserted).
-.. code-block:: none
+ trusted-enabled: this property exists when the firmware stack is booting
+ in trusted mode.
- 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.
+ 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.
- secure-enabled: this property exists if the system is booting in secure mode.
+ hw-key-hash-size: hw-key-hash size
- trusted-enabled: this property exists if the system is booting in trusted mode.
- hw-key-hash: hash of three concatenated hardware public key. This is required
- by the ROM code to verify images.
+Obsolete properties
+-------------------
+
+.. code-block:: none
+
+ hash-algo: Superseded by the hw-key-hash-size property in
+ 'ibm,secureboot-v2'.
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";
+ compatible = "ibm,secureboot-v2";
secure-enabled;
trusted-enabled;
+ hw-key-hash-size = <0x40>;
hw-key-hash = <0x40d487ff 0x7380ed6a 0xd54775d5 0x795fea0d 0xe2f541fe
- 0xa9db06b8 0x466a42a3 0x20e65f75 0xb4866546 0x17d907
+ 0xa9db06b8 0x466a42a3 0x20e65f75 0xb4866546 0x0017d907
0x515dc2a5 0xf9fc5095 0x4d6ee0c9 0xb67d219d 0xfb708535
0x1d01d6d1>;
phandle = <0x100000fd>;
@@ -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.
@@ -1,42 +1,156 @@
.. _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.
+
+Secure boot is initialized by calling *secureboot_init()* and its 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. See `doc/device-tree/ibm,secureboot.rst
+<device-tree/ibm,secureboot>` and `doc/device-tree/ibm,cvc.rst
+<device-tree/ibm,cvc>`.
+
+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*, 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``.
+
+``@hw_key_hash`` is used to check if the firware keys used to sign
+the firmware blob can be trusted.
+
+``@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*, 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 +158,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.
POWER9 changes reflected in the libstb: - bumped ibm,secureboot node to v2 - added ibm,cvc node - hash-algo superseded by hw-key-hash-size Signed-off-by: Claudio Carvalho <cclaudio@linux.vnet.ibm.com> --- doc/device-tree/ibm,secureboot.rst | 59 ++++---- doc/device-tree/tpm.rst | 6 +- doc/stb.rst | 298 ++++++++++++++++++------------------- 3 files changed, 181 insertions(+), 182 deletions(-)