diff --git a/source/reference-manual/security/imx-generic-custom-keys.rst b/source/reference-manual/security/imx-generic-custom-keys.rst index dc61744c2..817879126 100644 --- a/source/reference-manual/security/imx-generic-custom-keys.rst +++ b/source/reference-manual/security/imx-generic-custom-keys.rst @@ -1,30 +1,27 @@ -How to use custom keys ----------------------- +Using Custom Keys +----------------- -Create the keys -^^^^^^^^^^^^^^^ +Creating the Keys +^^^^^^^^^^^^^^^^^ -There are different ways to create and store the needed keys for the secure -boot. One important reference to understand how to generate the PKI tree is -`i.MX Secure Boot on HABv4 Supported Devices`_ application note from NXP. +There are different ways to create and store the keys needed for Secure Boot. +One reference for learning how to generate the PKI tree is the `i.MX Secure Boot on HABv4 Supported Devices`_ application note from NXP. -In addition, the U-Boot project also includes a documentation on `Generating a -fast authentication PKI tree`_. +In addition, the U-Boot project also includes documentation on `Generating a fast authentication PKI tree`_. -.. warning:: It is critical that the keys created in this process must be stored - in a secure and safe place. Once the keys are fused to the board and it is - closed, that board will only boot signed images. So the keys are required in - future steps. +.. warning:: + It is critical that the keys created in this process be stored in a secure and safe place. + Once the keys are fused to the board and it is closed, only signed images will boot. + The keys are required in future steps. -Generate the MfgTools scripts +Generate the MfgTools Scripts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There is a set of scripts to help with creating the set of commands used to fuse -the key into the fuse banks of ````, and to close the board which -configures the board to only boot signed images. +There are scripts to help with creating the commands to fuse the key into the fuse banks of ````, and to close the board. +This will configure the board to only boot signed images. -1. Clone the ``lmp-tools`` from GitHub +1. Clone ``lmp-tools`` from GitHub .. prompt:: bash host:~$ @@ -63,9 +60,7 @@ Where ```` can be found in the table below: - imx8mn_imx8mp .. note:: - For Toradex devices ``apalis-imx6-sec`` and ``apalis-imx8-sec``, provide the - additional ``-t`` parameter so the Toradex PIDs are included in the output - scripts. + For Toradex devices ``apalis-imx6-sec`` and ``apalis-imx8-sec``, provide the additional ``-t`` parameter so the Toradex PIDs are included in the output scripts. 4. Install the scripts to the ``meta-subscriber-overrides``: @@ -80,7 +75,7 @@ The content of ``mfgtool-files_%.bbappend`` should be:: FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" -5. Inspect the changes and push it accordingly +5. Inspect the changes, and push accordingly .. prompt:: bash host:~$ @@ -97,13 +92,12 @@ The result of ``git status`` should look like:: new file: recipes-support/mfgtool-files/mfgtool-files//fuse.uuu new file: recipes-support/mfgtool-files/mfgtool-files_%.bbappend -The changes add the UUU scripts to the ``mfgtool-files`` artifacts of next -targets. Run the ``fuse.uuu`` and ``close.uuu`` to fuse the custom keys and -close the board, respectively. +The changes add the UUU scripts to the ``mfgtool-files`` artifacts of next targets. +Run the ``fuse.uuu`` and ``close.uuu`` to fuse the custom keys and close the board, respectively. -.. warning:: The scripts ``fuse.uuu`` and ``close.uuu`` include commands which - result is irreversible. The scripts should be executed with caution and only - after understanding its critical implications. +.. warning:: + The scripts ``fuse.uuu`` and ``close.uuu`` include commands which result is irreversible. + The scripts should be executed with caution and only after understanding its critical implications. .. _i.MX Secure Boot on HABv4 Supported Devices: https://www.nxp.com/webapp/Download?colCode=AN4581&location=null .. _Generating a fast authentication PKI tree: https://github.com/nxp-imx/uboot-imx/blob/lf_v2022.04/doc/imx/habv4/introduction_habv4.txt diff --git a/source/reference-manual/security/secure-machines.rst b/source/reference-manual/security/secure-machines.rst index 721b230d7..231419676 100644 --- a/source/reference-manual/security/secure-machines.rst +++ b/source/reference-manual/security/secure-machines.rst @@ -2,44 +2,36 @@ .. _ref-secure-machines: -Machines with secure aspects enabled by FoundriesFactory +Machines with Secure Aspects Enabled by FoundriesFactory ======================================================== -The Linux microPlatform™ (LmP) provides machines with secure aspects enabled by default when using -FoundriesFactory. +The Linux® microPlatform (LmP) provides machines with secure aspects enabled by default. -The purpose of these machines is to gather the needed configuration to enable -secure boot and other security aspects and to provide a set of artifacts to help -in the process needed to have the hardware board set to secure boot. +These machines obtain the configuration needed to enable Secure Boot and other security aspects. +They provide a set of artifacts to help in the process of getting hardware set to Secure Boot. .. warning:: - It is recommended to read :ref:`ref-secure-boot-imx-habv4` - (for i.MX8 :ref:`ref-secure-boot-imx-ahab`) before proceeding with - the following steps. + It is recommended to read :ref:`ref-secure-boot-imx-habv4` (for i.MX8, :ref:`ref-secure-boot-imx-ahab`) before proceeding with the following steps. -Supported machines +Supported Machines ------------------ -* NXP iMX6ULL-EVK Secure: ``imx6ullevk-sec`` is the ``imx6ullevk`` machine configured to have secure boot enabled by default. -* NXP iMX8MMINILPD4 EVK Secure: ``imx8mm-lpddr4-evk-sec`` is the ``imx8mm-lpddr4-evk`` machine configured to have secure boot and secure storage enabled by default. -* NXP iMX8MNANOD4 EVK Secure: ``imx8mn-ddr4-evk-sec`` is the ``imx8mn-ddr4-evk`` machine configured to have secure boot and secure storage enabled by default. -* NXP iMX8MPLUSLPD4 EVK Secure: ``imx8mp-lpddr4-evk-sec`` is the ``imx8mp-lpddr4-evk`` machine configured to have secure boot and secure storage enabled by default. -* NXP Toradex Apalis-iMX6 Secure: ``apalis-imx6-sec`` is the ``apalis-imx6`` machine configured to have secure boot and secure storage enabled by default. -* NXP Toradex Apalis-iMX8 Secure: ``apalis-imx8-sec`` is the ``apalis-imx8`` machine configured to have secure boot and secure storage enabled by default. +* NXP iMX6ULL-EVK Secure: ``imx6ullevk-sec`` is the ``imx6ullevk`` machine configured to have Secure Boot enabled by default. +* NXP iMX8MMINILPD4 EVK Secure: ``imx8mm-lpddr4-evk-sec`` is the ``imx8mm-lpddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. +* NXP iMX8MNANOD4 EVK Secure: ``imx8mn-ddr4-evk-sec`` is the ``imx8mn-ddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. +* NXP iMX8MPLUSLPD4 EVK Secure: ``imx8mp-lpddr4-evk-sec`` is the ``imx8mp-lpddr4-evk`` machine configured to have Secure Boot and secure storage enabled by default. +* NXP Toradex Apalis-iMX6 Secure: ``apalis-imx6-sec`` is the ``apalis-imx6`` machine configured to have Secure Boot and secure storage enabled by default. +* NXP Toradex Apalis-iMX8 Secure: ``apalis-imx8-sec`` is the ``apalis-imx8`` machine configured to have Secure Boot and secure storage enabled by default. -How to enable -------------- +Enabling +-------- -The suggested way to enable a secure machine in a factory is to select the -correct platform when creating the factory. This might not be ideal as the -customer might want to evaluate their setup in an open state for easier -development. +The suggested way to enable a secure machine is to select the correct platform when creating your Factory. +However, this may not be ideal for evaluating your setup in an open state for easier development. -The platform definition comes from ``ci-scripts`` but due to computation limits, -the CI is configured to decline changes in the ``machines:`` parameter. When -attempting to replace or add a new machine in a factory, customers face this -issue:: +The platform definition comes from ``ci-scripts``, but due to computation limits, the CI is configured to decline changes in the ``machines:`` parameter. +When attempting to replace or add a new machine in a Factory, you will likely encounter something like:: remote: A new machine is being added: {''} remote: ERROR: Please contact support to update machines @@ -47,27 +39,14 @@ issue:: To https://source.foundries.io/factories//ci-scripts.git ! [remote rejected] master -> master (hook declined) -In this case, ask a support engineer to update the ``factory-config.yml`` file -in ``ci-scripts`` git repository for your FoundriesFactory to the following -configuration:: +In this case, you should open a support ticket. - machines: - - - - mfg_tools: - - machine: - params: - DISTRO: lmp-mfgtool - IMAGE: mfgtool-files - EXTRA_ARTIFACTS: mfgtool-files.tar.gz - -How to use ----------- +Using the Secure Machine +------------------------ -Trigger a platform build and wait until the target is created. +Trigger a platform build and wait until the Target is created. -Follow the steps from :ref:`ref-boards` to prepare the hardware and download the -same artifacts. +Follow the steps from :ref:`ref-boards` to prepare the hardware and download the same artifacts. The list of artifacts downloaded should be: @@ -77,11 +56,9 @@ The list of artifacts downloaded should be: * ``sit-.bin`` * ``u-boot-.itb`` - .. note:: - For the i.MX8* based machines, the ``SPL`` binary is included in ``imx-boot`` - and the user should refer to ``imx-boot-`` through this - document. + For i.MX8* based machines, the ``SPL`` binary is included in ``imx-boot``. + Refer to ``imx-boot-`` through this document. Expand the tarballs: @@ -109,12 +86,12 @@ The resultant directory tree should look like the following:: └── u-boot-.itb -Follow the ``readme.md`` under ``mfgtool-files-`` for instructions -to sign the SPL images, to fuse, and close the board. +Follow the ``readme.md`` under ``mfgtool-files-`` for instructions to sign the SPL images, to fuse, and close the board. -.. warning:: The **fuse** and **close** procedures are irreversible. The - instructions from the ``readme.md`` file should be followed and executed with - caution and only after understanding the critical implication of those commands. +.. warning:: + + The **fuse** and **close** procedures are irreversible. + The instructions from the ``readme.md`` file should be followed and executed with caution and only after understanding the critical implication of those commands. .. include:: imx-generic-custom-keys.rst @@ -127,7 +104,8 @@ Accessing Secure Storage Once a device has been successfully fused and closed, the secure storage RPMB becomes available. This is accessed through ``fiovb`` (Foundries.io™ Verified Boot) early trusted application from Open Portable-Trusted Execution Environment (OP-TEE). -By default, the secure storage only holds the variables used by ``aktualizr-lite`` to handle the updates, previously stored in ``uboot-env`` for non-fused boards. You can extend this to store custom variables that need to be made secure, like mac addresses, serial numbers and other critical device information. +By default, the secure storage only holds the variables used by ``aktualizr-lite`` to handle the updates, previously stored in ``uboot-env`` for non-fused boards. +You can extend this to store custom variables that need to be made secure, like mac addresses, serial numbers and other critical device information. Writing to Secure Storage ^^^^^^^^^^^^^^^^^^^^^^^^^