Quick_Start_Guide.md

1. Introduction

BG Networks' Embedded Security Software Architecture (ESSA) enhances cybersecurity for IoT devices, including secure boot, encryption, authentication, and secure software updates. The ESSA enables engineers to extend a hardware root of trust to secure U-Boot, the Linux kernel, and applications in the root file system.

2. Setup

The following packages are needed to build an image on a headless system. The build has been tested with Ubuntu 20.04 (LTS) and Ubuntu 22.04 (LTS).

sudo apt install -y gawk wget git diffstat unzip texinfo gcc build-essential \
chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 \
xterm python3-subunit mesa-common-dev zstd liblz4-tool snapd minicom

# If Python2.X has already been installed, we need to make sure that the
# python binary in the path is linked to python3
sudo apt install python-is-python3

# Downloading and installing repo tool
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/repo
chmod a+x ~/repo
sudo cp ~/repo /usr/bin

For other supported Linux distributions, please refer to the Yocto Project Reference Manual.

2. Yocto build

The following steps outline how to build an example BSP using the meta-essa layer.

Create a directory for the BSP:

mkdir ~/yocto
cd ~/yocto

Initialize and sync the repository:

# Initializing NXP BSP
repo init -u https://github.com/nxp-imx/imx-manifest.git -b imx-linux-kirkstone -m imx-5.15.32-2.0.0.xml

# Download ESSA manifest
wget --directory-prefix .repo/manifests https://raw.githubusercontent.com/bgnetworks/meta-essa/kirkstone/scripts/imx-5.15.32-2.0.0-bgn-essa.xml
repo init -m imx-5.15.32-2.0.0-bgn-essa.xml

repo sync -j$(nproc)

Setup the build environment based on the target machine:

# Targetting the i.MX6SX Sabre SD
MACHINE=imx6sxsabresd DISTRO=fsl-imx-fb source setup-essa.sh -b build

# Targetting the i.MX6UL EVK
MACHINE=imx6ulevk DISTRO=fslc-framebuffer source setup-essa.sh -b build

# Targetting the i.MX8MM EVK
MACHINE=imx8mmevk DISTRO=fsl-imx-wayland source setup-essa.sh -b build

Build the core image:

bitbake core-image-base

Note: The initial image build might take a few hours

4. Program the image into the board SD-card (i.MX6SX)

Install uuu tool:

sudo snap install universal-update-utility

Change to the image directory:

cd ~/yocto/build/tmp/deploy/images/imx6sxsabresd

The following shows all images created in build process. The full image for flash the iMX6SX SABRE EVK board is core-image-base-imx6sxsabresd.wic.bz2

Set the iMX6SX SABRE EVK board to serial download protocol (SDP) mode by configuring the boot configuration switches following Table 1.

MODE	SW10	SW11	SW12
SDP	00000000	00000000	00000000
SD4	00000000	00111000	01000000
QSPI	00000000	00000000	00011000

TABLE 1: Boot mode selection switches on i.MX 6SX EVK

---

Connect the board (J7 - USB OTG connector) to the build machine with type B-Micro USB cable:

Power up the board and confirm the board has been set up correctly:

uuu -lsusb

Flash the U-Boot and Yocto OS image:

uuu -b sd_all u-boot.imx core-image-base-imx6sxsabresd.wic.bz2

Power down the board and set the iMX6SX SABRE EVK board to the SD card (SD4) boot mode following Table 1

5. Connect to device as log in as root user

Setup minicom to configure serial communication:

sudo minicom -s

Open minicom:

sudo minicom

Connect to the iMX6SX SABRE EVK board J16 - Debug PORT 1 with a USB-UART cable. Power up the iMX6SX SABRE EVK board and log in as: root

6. Block encryption example: Creating an encrypted block device

An encrypted device can be created by using black keys. A black key is a secure key that can only be read back in an encrypted form. The following outlines steps to create an encrypted device, mount the device to the filesystem, add a file that is automatically encrypted, and access the encrypted device after rebooting.

Create black key and key blob using the CAAM:

caam-keygen create mykey ecb -s 16

Change to the keyblob directory: By default, the keys and blobs are created in KEYBLOB_LOCATION, which is in the /data/caam/ folder.

cd /data/caam

The keyblob directory contains two files: mykey and mykey.bb.

• mykey is a black key, called a Tagged Key, used for encryption during the current session.
• mykey.bb is black key blob, which is an encrypted form of the black key for encryption between power cycles.

This black key blob can be stored off device to ensure access to encrypted filesystem is maintained.

Add the key into the Linux keyring:

cat mykey | keyctl padd logon mykey1: @s

Create a file and link to loop device:

dd if=/dev/zero of=encrypted.img bs=1M count=32
losetup /dev/loop0 encrypted.img

Use the generated random key for block encryption:

dmsetup -v create myEncryptedBlock --table "0 $(blockdev --getsz /dev/loop0) crypt capi:tk(cbc(aes))-plain :36:logon:mykey1: 0 /dev/loop0 0 1 sector_size:512"

Build and mount the encrypted filesystem on the block device:

mkfs.ext4 /dev/mapper/myEncryptedBlock
mkdir -p /mnt/myBlock
mount /dev/mapper/myEncryptedBlock /mnt/myBlock

Test the filesystem by creating new file in the encrypted block:

echo "This is a test of disk encryption on i.MX" > /mnt/myBlock/readme.txt

Unmount and remove the encrypted block device:

umount /mnt/myBlock
dmsetup remove myEncryptedBlock

7. Block encryption example: Using an encrypted block device

Reboot the board and log in as: root

Import the block key blob to create the black key used for disk encryption, add the key to the Linux keyring, and use the key for the encrypted block device:

cd /data/caam
caam-keygen import mykey.bb importKey
cat mykey | keyctl padd logon mykey2: @s

losetup /dev/loop0 encrypted.img

dmsetup -v create myEncryptedBlock --table "0 $(blockdev --getsz /dev/loop0) crypt capi:tk(cbc(aes))-plain :36:logon:mykey2: 0 /dev/loop0 0 1 sector_size:512"

Mount the encrypted block:

mount /dev/mapper/myEncryptedBlock /mnt/myBlock

Read from device and verify readme contents:

cat /mnt/myBlock/readme.txt