Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup security secure-machines page #663

Merged
merged 1 commit into from
Jan 23, 2024
Merged

Cleanup security secure-machines page #663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 22 additions & 28 deletions source/reference-manual/security/imx-generic-custom-keys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Check failure on line 9 in source/reference-manual/security/imx-generic-custom-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.NXP-trademark] 'NXP' should be marked as a trademark first time it occurs in body of text.

Raw Output:
{"message": "[Fio-docs.NXP-trademark] 'NXP' should be marked as a trademark first time it occurs in body of text.", "location": {"path": "source/reference-manual/security/imx-generic-custom-keys.rst", "range": {"start": {"line": 9, "column": 133}}}, "severity": "ERROR"}

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 ``<machine>``, 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 ``<machine>``, 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:~$

Expand Down Expand Up @@ -63,9 +60,7 @@
- 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``:

Expand All @@ -80,7 +75,7 @@

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

5. Inspect the changes and push it accordingly
5. Inspect the changes, and push accordingly

.. prompt:: bash host:~$

Expand All @@ -97,13 +92,12 @@
new file: recipes-support/mfgtool-files/mfgtool-files/<machine>/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
86 changes: 32 additions & 54 deletions source/reference-manual/security/secure-machines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,72 +2,51 @@

.. _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.

Check warning on line 15 in source/reference-manual/security/secure-machines.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/secure-machines.rst", "range": {"start": {"line": 15, "column": 5}}}, "severity": "INFO"}

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: {'<machine>'}
remote: ERROR: Please contact support to update machines
remote: error: hook declined to update refs/heads/master
To https://source.foundries.io/factories/<factory>/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:
- <machine-sec>

mfg_tools:
- machine: <machine-sec>
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:

Expand All @@ -77,11 +56,9 @@
* ``sit-<machine-sec>.bin``
* ``u-boot-<machine-sec>.itb``


.. note::
For the i.MX8* based machines, the ``SPL`` binary is included in ``imx-boot``
and the user should refer to ``imx-boot-<machine-sec>`` through this
document.
For i.MX8* based machines, the ``SPL`` binary is included in ``imx-boot``.
Refer to ``imx-boot-<machine-sec>`` through this document.

Expand the tarballs:

Expand Down Expand Up @@ -109,12 +86,12 @@
└── u-boot-<machine-sec>.itb


Follow the ``readme.md`` under ``mfgtool-files-<machine-sec>`` for instructions
to sign the SPL images, to fuse, and close the board.
Follow the ``readme.md`` under ``mfgtool-files-<machine-sec>`` 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

Expand All @@ -127,7 +104,8 @@
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
^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down