foundriesio · kprosise · Oct 23, 2023 · Oct 18, 2023 · Oct 18, 2023 · Oct 18, 2023
diff --git a/source/reference-manual/factory/factory-sources.rst b/source/reference-manual/factory/factory-sources.rst
@@ -71,7 +71,7 @@ Configuring CI to Build New Branches
 
 By default, ``meta-subscriber-overrides``, ``lmp-manifest`` and ``containers``
 have the single branch, ``main``.
-For these repos it is reccomended to also have a ``devel`` branch for non-production purposes.
+For these repos it is recommended to also have a ``devel`` branch for non-production purposes.
 ``ci-scripts`` has the single default branch ``master``.
 
 Platform Branches

diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst
@@ -7,17 +7,25 @@
 
 If you are not familiar with the concept of Distro, the Yocto Project definition can help (`term-DISTRO`_), another good document is the `Poky`_ description, which is the default distro reference used by the Yocto Project.
 
+LmP supported distros are:
+
+* ``lmp``
+* ``lmp-base``
+* ``lmp-mfgtool``
+* ``lmp-wayland``
+* ``lmp-xwayland``
+
 .. note::
    For guidance on building new targets with a different distro and customizations, see: :ref:`Customizing the Distro <ref-customizing-the-distro>`.
 
-LmP
+lmp
 ***
 
 The ``lmp`` is the default distro for a FoundriesFactory. The main point of this distro is to configure the packages for working with OTA, and to organize the boot sequence, including the image architecture using OSTree and installing the needed artifacts.
 
 This is the default distro used when a FoundriesFactory is created.
 
-LmP Base
+lmp-base
 ********
 
 The ``lmp-base`` is the distro recommended for bring up and low level development (when the platform system is being developed or adjusted, for example).
@@ -36,25 +44,15 @@
 
 * The Linux Kernel binary, along with the required DTB files, are provided as separate files, instead of inside a boot image. This way the binaries can be replaced for testing purposes.
 
-To change the distro on a FoundriesFactory, from the ``ci-scripts`` git repository , update the ``factory-config.yml`` to include the ``DISTRO`` parameter under ``lmp:params``, which results in the following:
-
-    lmp:
-      params:
-        IMAGE: lmp-factory-image
-
-        DOCKER_COMPOSE_APP: "1"
-
-        DISTRO: lmp-base
-
-LmP MFGTools
-************
+lmp-mfgtool
+***********
 
-The distro used to generate the ``mfgtool-files`` artifacts which provide the deploy and update tool for some machines (i.MX family).
+The distro used to generate the ``mfgtool-files`` artifacts which provide the deploy and update tool for some machines.
 
 .. _ref-lmp-wayland-xwayland:
 
-LmP Wayland and LmP XWayland
-****************************
+lmp-wayland/lmp-xwayland
+************************
 
 The distros which provide Wayland and XWayland support on top of ``lmp`` distro.
 

diff --git a/source/reference-manual/security/factory-keys.rst b/source/reference-manual/security/factory-keys.rst
@@ -26,6 +26,9 @@
     The device RoT key (the key used for secure boot, for example) is shown in the diagrams.
     However it is not an online key and is not used during the FoundriesFactory® build.
 
+i.MX Secure Boot Flow
+"""""""""""""""""""""
+
 The following diagram shows the secure boot flow for i.MX machines (TF-A is present only for arm64 devices):
 
 .. graphviz::
@@ -54,6 +57,9 @@
         "Linux kernel"    -> "Linux kernel modules"              [label = "MODSIGN_PRIVKEY"];
    }
 
+STM32MP15 Secure Boot Flow
+""""""""""""""""""""""""""
+
 The following diagram shows the secure boot flow for STM32MP15-based machines:
 
 .. graphviz::
@@ -84,6 +90,9 @@
         "Linux kernel"       -> "Linux kernel modules"  [label = "MODSIGN_PRIVKEY"];
    }
 
+UEFI Secure Boot Flow
+"""""""""""""""""""""
+
 The following diagram shows the secure boot flow (when booting with UEFI)
 for ``intel-corei7-64`` based machines:
 
@@ -105,6 +114,8 @@
         "Linux kernel"          -> "Linux kernel modules" [label = "MODSIGN_PRIVKEY"];
    }
 
+FoundriesFactory Keys
+---------------------
 
 When a Factory is created, by default, two sets of keys are created under
 ``lmp-manifest`` repository:
@@ -174,7 +185,7 @@
         │   └── x509_modsign.crt
 
 How to Rotate the FoundriesFactory Keys
----------------------------------------
+"""""""""""""""""""""""""""""""""""""""
 
 Each Factory is created with a unique key set. However, it is highly
 recommended to rotate the keys as needed. The suggestion is to rotate them each
@@ -185,12 +196,14 @@
   the used keys often. So, it is highly recommended to rotate the keys each 6 to 24
   months.
 
+  Please note that, depending on the key, it may be required to trigger a :ref:`ref-boot-software-updates` to correctly change the FoundriesFactory keys used. A mismatch in used keys could lead to devices failing to boot, which would then rollback to the previous stable version using the old keys.
+
 In the following sections, the command line on how to create the key pair for U-Boot,
 OP-TEE and Linux Kernel Modules is shown. Assuming the ``lmp-manifest`` repository is
 cloned inside ``<factory>`` directory.
 
 U-Boot Keys
-"""""""""""
+~~~~~~~~~~~
 
 .. _ref-factory-key-ubootdev:
 
@@ -219,7 +232,7 @@
 .. _ref-factory-key-opteedev:
 
 OP-TEE Keys
-"""""""""""
+~~~~~~~~~~~
 
 .. prompt:: bash host:~$
 
@@ -233,7 +246,7 @@
 .. _ref-factory-key-tfa:
 
 TrustedFirmware-A Keys
-"""""""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~~~~
 
 For TF-A keys:
 
@@ -249,7 +262,7 @@
 .. _ref-factory-key-linux-module:
 
 Linux Kernel Modules Keys
-"""""""""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A configuration file is needed to create the key used by Linux Kernel to sign
 the modules. The `Linux Kernel documentation`_ states the parameters required
@@ -314,4 +327,7 @@
      # TF-A Trusted Boot
      TF_A_SIGN_KEY_PATH = "${TOPDIR}/conf/factory-keys/tf-a/privkey_ec_prime256v1.pem"
 
+  This blog post shows how to identify which keys are being used during boot time: `How to read the boot logs to check the used keys`_.
+
 .. _Linux Kernel documentation: https://www.kernel.org/doc/html/v5.0/admin-guide/module-signing.html
+.. _How to read the boot logs to check the used keys: https://foundries.io/insights/blog/checking-log-secure/
diff --git a/source/reference-manual/security/ff-security-summary.rst b/source/reference-manual/security/ff-security-summary.rst
@@ -1,13 +1,13 @@
 Summary of Crypto Keys Used by FoundriesFactory
 ===============================================
 
-This page provides a brief summary cryptographic keys used by FoundriesFactory®.
-For detailed information on each key, please check the relevant page under :ref:`ref-security`.
+This page provides a brief summary of cryptographic keys used by FoundriesFactory®.
 
 Secure Connection to Cloud Services
 -----------------------------------
 
 These certificates are required to access the FoundriesFactory CI servers.
+For detailed information, check :ref:`ref-secure-cloud-services`.
 
 .. list-table:: Device Gateway Certificates Summary
    :header-rows: 1
@@ -31,6 +31,9 @@ These certificates are required to access the FoundriesFactory CI servers.
 Secure Boot (Hardware Root of Trust)
 ------------------------------------
 
+The Hardware Root of Trust depends on the SoC used.
+Please refer to :ref:`ref-secure-boot` pages and to the vendor reference manual for more information.
+
 .. list-table:: Secure Boot Certificates Summary
    :header-rows: 1
 
@@ -41,16 +44,13 @@ Secure Boot (Hardware Root of Trust)
      - Depends on the SoC
      - Owned and managed by the customer (offline key)
 
-The Hardware Root of Trust depends on the SoC used.
-Please refer to :ref:`ref-secure-boot` pages and
-to the vendor reference manual for more information.
-
 Secure Online Keys for Boot Stack
 ---------------------------------
 
+The detailed description for the LmP Build certificates, including diagrams for the boot flow, is in :ref:`ref-factory-keys`.
+
 The exact list of keys used for the boot stack depends on the hardware used.
-Some platforms will not make use of all keys.
-A list of available keys for an LmP build can be found below:
+Some platforms will not make use of all keys. A list of available keys for an LmP build can be found below:
 
 .. list-table:: LmP Build Certificates Summary
    :header-rows: 1
@@ -84,12 +84,12 @@ A list of available keys for an LmP build can be found below:
      - Owned by the customer, available as an online key for FoundriesFactory CI
      - ``TF_A_SIGN_KEY_PATH``
 
-The detailed description for the LmP Build certificates,
-including diagrams for the boot flow, is in :ref:`ref-factory-keys`.
-
 Secure Over the Air Updates
 ---------------------------
 
+Keys used to deliver secure software updates to FoundriesFactory devices.
+Additional information can be found in :ref:`ref-ota-security`.
+
 .. list-table:: Secure OTA Certificates Summary
    :header-rows: 1
 

diff --git a/source/user-guide/troubleshooting/troubleshooting.rst b/source/user-guide/troubleshooting/troubleshooting.rst
@@ -254,6 +254,41 @@
 
   fioctl targets prune --by-tag <tag> --keep-last <number> --dryrun
 
+Device Registration Common Errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Even if the device has a proper internet connection, users can still run into errors during device registration.
+The ``lmp-device-register`` provides some diagnostics in the error message without exposing sensitive information to avoid possible attack vectors.
+
+Here, we show additional information to help debug of common errors encountered during the registration:
+
+.. code-block::
+
+   Unable to create device: HTTP_401
+   Polis Error: {"error":"not_found","error_description":"Cannot find a user with the provided token","status":404}
+
+This indicates a problem with the token.
+
+**Solution:** Verify there is a valid non-expired token in https://app.foundries.io/settings/tokens/.
+
+.. code-block::
+
+   Unable to create device: HTTP_403
+   message: A factory admin must add you to a team with one of these scopes: home-hub:devices:create
+
+This indicates no permission to create a device in the Factory.
+
+**Solution:** Verify the user token has ``device:create`` scope in https://app.foundries.io/settings/tokens/.
+If the Factory has :ref:`ref-team-based-access` set, check if the user is part of a team which has ``device:create`` permissions.
+
+.. code-block::
+
+   Error authorizing device: 'scope' parameter is not valid: wrong Factory value
+
+This usually means the device is running an image which was built locally and not on FoundriesFactory CI.
+
+**Solution:** Flash an image built from CI.
+
 .. _ref-ts-howto:
 
 How Tos
@@ -435,6 +470,61 @@
 
 4. Lastly, perform the registration again.
 
+.. _ref-ts-fiovb-container:
+
+Read Secure Variables from Containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After a board is fused and closed, the secure storage (RPMB) becomes available and handles the necessary variables to perform the OTA logic.
+Secure storage also can be leveraged to store custom device information, like MAC addresses, serial numbers, and other relevant values.
+
+You may wish to retrieve these values from the application. Please refer to the `fiovb-container <https://github.com/foundriesio/containers/tree/master/fiovb-container>`_ example, which brings a simple application to run ``fiovb_printenv`` from inside a container.
+
+.. _ref-ts-bootdelay:
+
+Enable U-Boot Boot Delay
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, LmP disables U-Boot's boot delay feature for security purposes. However, this is a powerful ally during the development phase, as it provides direct access to U-Boot's environment for debugging.
+
+* **Secured/Closed Boards**
+
+This requires changing the ``lmp.cfg`` U-Boot config fragment in order to override ``CONFIG_BOOTDELAY=-2`` set by default in LmP.
+
+1. Create ``bootdelay.cfg`` configuration fragment:
+
+**meta-subscriber-overrides/recipes-bsp/u-boot/u-boot-fio/<machine>/bootdelay.cfg:**
+
+.. code-block::
+
+   CONFIG_BOOTDELAY=3
+
+2. Append it to the U-Boot source:
+
+**meta-subscriber-overrides/recipes-bsp/u-boot/u-boot-fio_%.bbappend**
+
+.. code-block::
+
+   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
+
+   SRC_URI:append = " \
+       file://bootdelay.cfg \
+   "
+
+After pushing to the Factory, it is necessary to trigger :ref:`ref-boot-software-updates` for the devices to take the update, or re-flash the device entirely to include this change.
+
+* **Open Boards**
+
+Open/non-secured boards also benefit from the procedure detailed for secured boards, however as they rely on U-Boot env support, there is a handier way on enabling boot delay during runtime:
+
+.. prompt::
+
+   $ sudo su
+   # fw_setenv bootdelay 3
+   # reboot
+
+After reboot, the device shows the U-Boot bootdelay prompt.
+
 .. _ref-ts-tips:
 
 Tips and Abouts