doc: update libstb documentation with POWER9 changes

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>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

3 files changed, 181 insertions, 182 deletions

diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst
index 948c7e03..42c4ed7d 100644
--- a/doc/device-tree/ibm,secureboot.rst
+++ b/doc/device-tree/ibm,secureboot.rst
@@ -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>;
diff --git a/doc/device-tree/tpm.rst b/doc/device-tree/tpm.rst
index d4e76678..a8e67bc0 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 2004af87..078c0f2b 100644
--- a/doc/stb.rst
+++ b/doc/stb.rst
@@ -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.