Machines with Secure Aspects Enabled by FoundriesFactory

The Linux® microPlatform (LmP) provides machines with secure aspects enabled by default.

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 Secure Boot on i.MX 6/7/8M 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.

Enabling

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, 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, you should open a support ticket.

Using the Secure Machine

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 i.MX8* based machines, the SPL binary is included in imx-boot. 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.

Using Custom Keys

Creating the Keys

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 documentation on Generating a fast authentication PKI tree.

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

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

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.

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