Machines with secure aspects enabled by FoundriesFactory

The Linux microPlatform™ (LmP) provides machines with secure aspects enabled by default when using FoundriesFactory.

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.

Warning

It is recommended to read Secure Boot on i.MX 6/7/8M Families using HABv4 (for i.MX8 Secure Boot on i.MX 8/8X Families using AHAB including 8QM) before proceeding with the following steps.

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.

How to enable

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 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:

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:

machines:
- <machine-sec>

mfg_tools:
- machine: <machine-sec>
    params:
    DISTRO: lmp-mfgtool
    IMAGE: mfgtool-files
    EXTRA_ARTIFACTS: mfgtool-files.tar.gz
    UBOOT_SIGN_ENABLE: "1"

How to use

Trigger a platform build and wait until the target is created.

Follow the steps from Supported Boards to prepare the hardware and download the same artifacts.

The list of artifacts downloaded should be:

  • mfgtool-files-<machine-sec>.tar.gz
  • lmp-factory-image-<machine-sec>.wic.gz
  • SPL-<machine-sec>
  • 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.

Expand the tarballs:

gunzip lmp-factory-image-<machine-sec>.wic.gz
tar -zxvf mfgtool-files-<machine-sec>.tar.gz

The resultant directory tree should look like the following:

├── lmp-factory-image-<machine-sec>.wic
├── mfgtool-files-<machine-sec>
│   ├── bootloader.uuu
│   ├── close.uuu
│   ├── full_image.uuu
│   ├── fuse.uuu
│   ├── readme.md
│   ├── SPL-mfgtool
│   ├── u-boot-mfgtool.itb
│   ├── uuu
│   └── uuu.exe
├── mfgtool-files-<machine-sec>.tar.gz
├── SPL-<machine-sec>
├── sit-<machine-sec>.bin
└── 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.

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.

How to use custom keys

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

In addition, the U-Boot project also includes a 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.

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.

  1. Clone the lmp-tools from GitHub
git clone git://github.com/foundriesio/lmp-tools.git
  1. Export the path to where keys are stored
export KEY_FILE=/path-to-key-files/<efusefile>
  1. Generate the scripts to fuse and close the board
./lmp-tools/security/<soc>/gen_fuse.sh -s $KEY_FILE -d ./fuse.uuu
./lmp-tools/security/<soc>/gen_close.sh -s $KEY_FILE -d ./close.uuu

Where <soc> can be found in the table below:

Table 7 SoCs covered by each <soc> folder
SoC <soc> folder
imx6qdl and variants imx6
imx6ul, imx6ull imx6ul
imx7ulp imx7ulp
imx8mq, imx8mm imx8m
imx8mn, imx8mp imx8mn_imx8mp
  1. Install the scripts to the meta-subscriber-overrides:
mkdir -p <factory>/meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/<machine>
cp fuse.uuu <factory>/meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/<machine>
cp close.uuu <factory>/meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files/<machine>
cat <factory>/meta-subscriber-overrides/recipes-support/mfgtool-files/mfgtool-files_%.bbappend

The content of mfgtool-files_%.bbappend should be:

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
  1. Inspect the changes and push it accordingly
git status

The result of git status should look like:

On branch devel
Your branch is up to date with 'origin/devel'.

Changes to be committed:
(use "git restore --staged <file>..." to unstage)
    new file:   recipes-support/mfgtool-files/mfgtool-files/<machine>/close.uuu
    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.

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.

Accessing Secure Storage

Note

The LmP leverages the eMMC Replay Protected Memory Block (RPMB) as secure storage. This section is only applicable for devices that provide this feature.

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.

Writing to Secure Storage

fiovb_setenv <variable> <value>

Reading From Secure Storage

fiovb_printenv <variable>