To maintain a high level of security, strictly limit the number of people who have access to the private keys to sign the device artifacts. In many cases, this means that only specific persons—signers—have access to them, and these individuals may or may not be part of the development team.

TrustFence standalone signing and encryption tools allow you to isolate the signing/encryption processes from firmware image generation. This way, there is no need to secure the entire development environment, only a secure location in which the firmware images get signed and encrypted.

Requirements:

  1. Enable Trustfence in your Digi Embedded Yocto project by adding the following line to your local.conf file:

    INHERIT += "trustfence"

  2. Use that project to generate an SDK.

    $ bitbake -c populate_sdk dey-image-qt

  3. Install the generated SDK and source it.

    $ <YOCTO_PROJECT_FOLDER>/tmp/deploy/sdk/dey-glibc-x86_64-dey-image-qt-xwayland-aarch64-ccimx8x-sbc-pro-toolchain-3.2-r3.sh
$ source <SDK_INSTALLATION_PATH>/environment-setup-aarch64-dey-linux

Sign and encrypt U-Boot images

Authentication of signed boot artifacts is not enabled on the default U-Boot configuration. You must enable the configuration option CONFIG_AUTH_ARTIFACTS either by adding the configuration to your board’s defconfig if you are building U-Boot externally, or by adding the following line to your Digi Embedded Yocto project’s conf/local.conf:

conf/local.conf
UBOOT_EXTRA_CONF += "CONFIG_AUTH_ARTIFACTS=y"

Once the toolchain is installed and sourced, you can follow these steps to sign a U-Boot image:

  1. Configure the signature process using the following environment variables:

    • CONFIG_SIGN_KEYS_PATH: (Mandatory) The path to the PKI tree. A new PKI tree is generated if an empty folder is specified.

    • CONFIG_KEY_INDEX: (Optional) Default value is 0. Index of the key to use for signatures.

    • CONFIG_SIGN_MODE: (Mandatory) Must be set to "AHAB"

    • CONFIG_MKIMAGE_LOG_PATH: (Optional) Path to the mkimage-<target>.log file. Depending on the U-Boot file you wish to sign and encrypt, <target> should be flash or flash_regression_linux_m4. The signing script requires this log to obtain layout information used to sign U-Boot.

      After you have built the Digi Embedded Yocto firmware, you can find these log files inside the project directory at: <project_folder>/tmp/deploy/images/ccimx8x-sbc-pro/imx-boot-tools. If you do not define this value, the signing script will look for a mkimage.log file in the directory it is being called from.

    • SRK_REVOKE_MASK: (Optional) Bitmask of the revoked SRKs.

    • ENABLE_ENCRYPTION: (Optional) If defined, the signed images are encrypted.

    • CONFIG_DEK_PATH: (Mandatory if ENABLE_ENCRYPTION is defined, otherwise ignored) The path to the data encryption key. If the file does not exist, a random 256-bit file is generated.

      You can also define these variables in a file .config located in the current path:

      .config
      CONFIG_SIGN_KEYS_PATH="/path/to/keys"
CONFIG_KEY_INDEX="3"

# In order to encrypt the images, also add the following:
#export ENABLE_ENCRYPTION="y"
#export CONFIG_DEK_PATH="/path/to/keys/dek.bin"

  2. Execute the trustfence-sign-uboot.sh script with the input file (U-Boot image to be signed) as the first parameter and the output file (signed and encrypted U-Boot image) as the second parameter:

    $ trustfence-sign-uboot.sh imx-boot.bin imx-boot-signed.bin
Using existing PKI tree
Signed image ready: imx-boot-signed.bin

The tool will also generate the SRK_efuses.bin file for the PKI tree used.

Sign and encrypt other images

The trustfence-sign-artifact.sh script allows generation of the following signed and encrypted artifacts:

  • Linux images

  • Device tree blobs and overlays

  • U-Boot bootscripts

  • Initramfs

To use the script, follow these steps:

  1. Configure the signature process using the following environment variables:

    • CONFIG_SIGN_KEYS_PATH: (Mandatory) The path to the PKI tree. If an empty path is specified, a new PKI tree is generated

    • CONFIG_KEY_INDEX: (Optional) Default value is 0. Index of the key to use for signatures.

    • CONFIG_DEK_PATH: (Optional) Path to the data encryption key. If undefined, the images will not be encrypted. If the file does not exist, a random 256-bit file is generated.

      In a similar way, you can also define these variables in a .config file located in the current path:

      .config
      CONFIG_SIGN_KEYS_PATH="/path/to/keys"
CONFIG_DEK_PATH="/path/to/dek"

  2. Execute the trustfence-sign-artifact.sh script. Syntax of the script is as follows:

    Usage: trustfence-sign-artifact.sh [OPTIONS] input-unsigned-image output-signed-image

    -p <platform>    select platform for the project
    -b               sign/encrypt bootscript
    -d               sign/encrypt DTB
    -o               sign/encrypt DTB overlay
    -i               sign/encrypt initramfs
    -l               sign/encrypt Linux image
    -r               sign read-only rootfs image

Supported platforms: ccimx6, ccimx6ul, ccimx8x, ccimx8mn, ccimx8mm

    The following example generates a signed and encrypted Image.gz:

    $ trustfence-sign-artifact.sh -p ccimx8x -l Image.gz Image.gz-signed