Skip to content

Latest commit

 

History

History
253 lines (171 loc) · 7.71 KB

Quick_Start_Guide.md

File metadata and controls

253 lines (171 loc) · 7.71 KB
Raw

BGN_logo

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. This document will guide the user on implementing BG Network’s ESSA on a NXP’s i.MX 6UL EVK board (imx6ulevk).

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

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

# 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 outlines the steps needed build the core image using Yocto with BGN-ESSA.

Create directory for the ESSA BSP for the i.MX 6UL EVK board:

mkdir ~/meta-bgn-essa-mx6ul
cd ~/meta-bgn-essa-mx6ul

Initialize and sync repository:

# Initiating NXP BSP
repo init -u git://source.codeaurora.org/external/imx/imx-manifest.git -b imx-linux-hardknott -m imx-5.10.52-2.1.0.xml

# Download ESSA manifest
wget --directory-prefix .repo/manifests https://raw.githubusercontent.com/bgnetworks/meta-essa-mx6ul/hardknott/scripts/imx-5.10.52-2.1.0-bgn-essa.xml
repo init -m imx-5.10.52-2.1.0-bgn-essa.xml

repo sync -j$(nproc)

The following files and directories are located in the meta-essa-mx6ul directory:

sync_dir

The Yocto meta directories are located in the sources directory:

yocto_meta_dir

Setup the build environment:

MACHINE=imx6ulevk DISTRO=fslc-framebuffer source mx6ul-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

Install uuu tool:

sudo snap install universal-update-utility

Change to the image directory:

cd ~/meta-bgn-essa-mx6ul/build/tmp/deploy/images/imx6ulevk

The following shows all images created in build process. The full image for flash the i.MX 6UL EVK board is core-image-base-imx6ulevk.wic.bz2

yocto_out_dir

Set the i.MX 6UL EVKboard to serial download protocol (SDP) mode by configuring the boot configuration switches following Table 1.

MODE SW602 SW601
SDP 01 XXXX
MicroSD 10 0010

TABLE 1: Boot mode selection switches on i.MX 6UL EVK (ref)

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

uuu -lsusb

uuu_lsusb

Flash the U-Boot and Yocto OS image:

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

Power down the board and set the i.MX 6UL EVKboard 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

minicom_setup1 minicom_setup2 minicom_setup3

Open minicom:

sudo minicom

Connect to the i.MX 6UL EVK board J16 - Debug PORT 1 with a USB-UART cable. Power up the i.MX 6UL EVKboard and log in as: root

6. Block encryption example: Creating an encrypted block device

An encrypted device can be created using a black key mechanism supported by the i.MX6UL. 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 i.MX6UL’s 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.

black_key_creation

  • 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 i.MX 6UL EVK 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

enc_test