From a7457b177234ad4eaae5486a8f656f2e651a52d4 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 10:51:56 -0300 Subject: [PATCH 01/11] rm: factory-sources: fix typo Signed-off-by: Vanessa Maegima --- source/reference-manual/factory/factory-sources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference-manual/factory/factory-sources.rst b/source/reference-manual/factory/factory-sources.rst index 0e6b00d8f..7ad9debb6 100644 --- 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 From df1a55c84fb7f21131c833cbf9c18c997a67f0c3 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:04:19 -0300 Subject: [PATCH 02/11] rm: linux-distro: include distro list and match exact distro names This covers feedback from CS team to clarify the use of distros. Signed-off-by: Vanessa Maegima --- .../reference-manual/linux/linux-distro.rst | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst index d5ef40562..58a735db3 100644 --- a/source/reference-manual/linux/linux-distro.rst +++ b/source/reference-manual/linux/linux-distro.rst @@ -7,17 +7,25 @@ LmP provides reference distros to be used in different use cases. They state the 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 `. -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). @@ -46,15 +54,15 @@ To change the distro on a FoundriesFactory, from the ``ci-scripts`` git reposito 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). .. _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. From 21955da876170d121d6fed55783445da278e53dc Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:05:12 -0300 Subject: [PATCH 03/11] rm: linux-distro: remove i.mx note for mfgtool distro lmp-mfgtool is now used across different SoC families and not only i.mx, so fix that. Signed-off-by: Vanessa Maegima --- source/reference-manual/linux/linux-distro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst index 58a735db3..a66e8e170 100644 --- a/source/reference-manual/linux/linux-distro.rst +++ b/source/reference-manual/linux/linux-distro.rst @@ -57,7 +57,7 @@ To change the distro on a FoundriesFactory, from the ``ci-scripts`` git reposito 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: From 6ca76ae5741821f4904921b50d2179c8ce12e973 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:09:43 -0300 Subject: [PATCH 04/11] rm: linux-distro: remove example to change distros This is now covered under Platform Customizing, so remove this example for maintainability. Signed-off-by: Vanessa Maegima --- source/reference-manual/linux/linux-distro.rst | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst index a66e8e170..73f6d3224 100644 --- a/source/reference-manual/linux/linux-distro.rst +++ b/source/reference-manual/linux/linux-distro.rst @@ -44,16 +44,6 @@ It overrides some configurations from ``lmp`` to generate a friendly system for * 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-mfgtool *********** From 72cf52cb87d160313da1fbc51495feb2ec494820 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:26:52 -0300 Subject: [PATCH 05/11] rm: security: summary: reorganize information Make the page clearer so we have a directly link to point to customers that links to the needed information. Signed-off-by: Vanessa Maegima --- .../security/ff-security-summary.rst | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/reference-manual/security/ff-security-summary.rst b/source/reference-manual/security/ff-security-summary.rst index e2d25fa0e..239baee43 100644 --- 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 From 84c99e4b15de565af88d2582d6e73ef2a6974a30 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:32:55 -0300 Subject: [PATCH 06/11] rm: security: factory-keys: improve handling of headers This brings us directly links that can be pointed to customers for each specific architecture. Signed-off-by: Vanessa Maegima --- .../security/factory-keys.rst | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/source/reference-manual/security/factory-keys.rst b/source/reference-manual/security/factory-keys.rst index e01099e51..cd0d45713 100644 --- a/source/reference-manual/security/factory-keys.rst +++ b/source/reference-manual/security/factory-keys.rst @@ -26,6 +26,9 @@ to configure the keys used by the Yocto Project. 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 @@ The following diagram shows the secure boot flow for i.MX machines (TF-A is pres "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 @@ The following diagram shows the secure boot flow for STM32MP15-based machines: "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 @@ for ``intel-corei7-64`` based machines: "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 @@ The directory structure is shown below: │ └── 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 @@ -190,7 +201,7 @@ OP-TEE and Linux Kernel Modules is shown. Assuming the ``lmp-manifest`` reposito cloned inside ```` directory. U-Boot Keys -""""""""""" +~~~~~~~~~~~ .. _ref-factory-key-ubootdev: @@ -219,7 +230,7 @@ For ``spldev``: .. _ref-factory-key-opteedev: OP-TEE Keys -""""""""""" +~~~~~~~~~~~ .. prompt:: bash host:~$ @@ -233,7 +244,7 @@ OP-TEE Keys .. _ref-factory-key-tfa: TrustedFirmware-A Keys -""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~ For TF-A keys: @@ -249,7 +260,7 @@ For TF-A keys: .. _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 From 092ffd4014703cab725b8a07342e6472db66ffcb Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:37:57 -0300 Subject: [PATCH 07/11] rm: security: factory-keys: include note to blog This blog brings helpful information when trying to use different set of keys in the factory. Signed-off-by: Vanessa Maegima --- source/reference-manual/security/factory-keys.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/reference-manual/security/factory-keys.rst b/source/reference-manual/security/factory-keys.rst index cd0d45713..c623af713 100644 --- a/source/reference-manual/security/factory-keys.rst +++ b/source/reference-manual/security/factory-keys.rst @@ -325,4 +325,7 @@ as shown in the following command: # 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/ From 7646e79cefa3c63b4d199174ea6df24b082e4ce0 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 11:44:14 -0300 Subject: [PATCH 08/11] rm: security: factory-keys: add note about triggering a boot fw update This is required in case there is a change in the used build keys. Signed-off-by: Vanessa Maegima --- source/reference-manual/security/factory-keys.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/reference-manual/security/factory-keys.rst b/source/reference-manual/security/factory-keys.rst index c623af713..b55090629 100644 --- a/source/reference-manual/security/factory-keys.rst +++ b/source/reference-manual/security/factory-keys.rst @@ -196,6 +196,8 @@ recommended to rotate the keys as needed. The suggestion is to rotate them each 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 ```` directory. From eb14b4cfeaf4ec95c00fbd33ff5d635d9bae9966 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 16:41:16 -0300 Subject: [PATCH 09/11] ug: troubleshooting: add common registration errors and solutions Signed-off-by: Vanessa Maegima --- .../troubleshooting/troubleshooting.rst | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/source/user-guide/troubleshooting/troubleshooting.rst b/source/user-guide/troubleshooting/troubleshooting.rst index 335b34552..d97caf735 100644 --- a/source/user-guide/troubleshooting/troubleshooting.rst +++ b/source/user-guide/troubleshooting/troubleshooting.rst @@ -254,6 +254,41 @@ This lets you can check the pruned targets before running the actual command:: fioctl targets prune --by-tag --keep-last --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 From c6def7fb00e9b7e6a23482721185178232ae9088 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 16:50:58 -0300 Subject: [PATCH 10/11] ug: troubleshooting: add note about fiovb-container This is used to run fiovb_printenv from a container to retrieve custom RPMB variables. Signed-off-by: Vanessa Maegima --- source/user-guide/troubleshooting/troubleshooting.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/user-guide/troubleshooting/troubleshooting.rst b/source/user-guide/troubleshooting/troubleshooting.rst index d97caf735..4725f26fa 100644 --- a/source/user-guide/troubleshooting/troubleshooting.rst +++ b/source/user-guide/troubleshooting/troubleshooting.rst @@ -470,6 +470,16 @@ Follow these steps to do so: 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 `_ example, which brings a simple application to run ``fiovb_printenv`` from inside a container. + .. _ref-ts-tips: Tips and Abouts From 7c6e41c5204ef06986ad6127120a009dc855e4ec Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Wed, 18 Oct 2023 18:28:50 -0300 Subject: [PATCH 11/11] ug: troubleshooting: add instructions on changing boot delay Signed-off-by: Vanessa Maegima --- .../troubleshooting/troubleshooting.rst | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/source/user-guide/troubleshooting/troubleshooting.rst b/source/user-guide/troubleshooting/troubleshooting.rst index 4725f26fa..938f8fba4 100644 --- a/source/user-guide/troubleshooting/troubleshooting.rst +++ b/source/user-guide/troubleshooting/troubleshooting.rst @@ -480,6 +480,51 @@ Secure storage also can be leveraged to store custom device information, like MA You may wish to retrieve these values from the application. Please refer to the `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//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