Machines with secure aspects enabled by FoundriesFactory

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 i.MX Secure Boot on HABv4 Supported Devices (for i.MX8 Secure Boot on i.MX 8 and i.MX 8X Families using AHAB) 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 iMX8M-MINILPD4 EVK Secure: imx8mm-lpddr4-evk-sec is the imx8mmevk 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 script to fuse the board
./lmp-tools/security/<soc>/gen_fuse.sh -s $KEY_FILE -d ./fuse.uuu
  1. Generate the script to close the board
./lmp-tools/security/<soc>/gen_close.sh -s $KEY_FILE -d ./close.uuu
  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}:"

SRC_URI:append:<machine> = " \
    file://fuse.uuu \
    file://close.uuu \
"

do_deploy:prepend:<machine>() {
    install -d ${DEPLOYDIR}/${PN}
    install -m 0644 ${WORKDIR}/fuse.uuu ${DEPLOYDIR}/${PN}/fuse.uuu
    install -m 0644 ${WORKDIR}/close.uuu ${DEPLOYDIR}/${PN}/close.uuu
}

Tip

Replace the machine name in case the factory is using a custom machine name.

  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.