...
Page properties | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Multiexcerpt include | ||||
---|---|---|---|---|
|
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Security
With increasing digitization and networking, the protection of embedded systems against unauthorized access and targeted attacks is more important than ever. Guaranteeing this type of security, along with functional security, is a major challenge in electronics design. PHYTEC supports you in minimizing risks by considering security requirements during the development of our hardware and board support packages. On top of these deployment-ready solutions, we support you with individual project consulting on complex security principles.
Security is a process encompassing all parts of a device and all development phases of its lifetime.
Compatible Controllers and Features
The following table lists the compatible controller as well as any other necessary information to use this manual.
Note | ||
---|---|---|
| ||
Please make sure your controller can be found on one of these tables before beginning. |
NXP i.MX6 and i.MX6UL/ULL
Scroll Title | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||
|
NXP i.MX8 Series
Scroll Title | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||
|
Short Crypto Refresher
Scroll Title | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
|
Recommended Security Requirements
As of the writing of this manual, recommendations apply to key lengths, certificates, and hash values. These recommendations come from BSI (Bundesamt für Sicherheit in der Informationstechnik) and NIST (National Institute of Standards and Technology).
Security Features in PHYTEC Standard BSP
In the technical and connected world, it is important to build a "security by design” approach that thwarts intrusion into your product, data, and intellectual property at multiple levels.
Here are the Security features from the Standard BSP.
Basic Security
Basic Security is the fundament of the security measures implementations and includes support for basic modules such as:
- True Number Generator and Cryptographic support
- Secure Boot
- Secure Key Storage and Usage
- Secure Storage
- Secure Updates
Parts from Access Control as an Example
Access Control regulates the access of users and services to the device and components in the device according to the least privilege access principle.
- Secure Console
- Secure Shell
- User and Role Management
More Additional Security Features (not part of this BSP)
Network Security
Network Security enables secure connections to connected devices or servers via Ethernet, WLAN, and LTE, but also secures access to the device from outside.
- Remote Access
- Server, Cloud Integration Tools
- Intrusion Protection
- Firewall
- Container
Interface Security
Interface Security secures the interfaces
...
against third-party access and enables the secure connection of intended devices.
Hardening
Hardening refers to the reduction of software components and kernel configuration to a necessary minimum.
Physical Security
Physical Security secures the device from direct physical access to protect the corresponding application and data from external access.
- Secure Debug
- Tamper Protection
- Housing
- Encapsulation of the circuit board
Provisioning
Provisioning includes the activation of hardware security features like Secure Boot and the generation of specific keys and X509 certificates on the device in secure manufacturing like the PHYTEC secure production area.
Introduction to Yocto and Board Support Packages
This document assumes that you are familiar with our Yocto BSPs. The basics of our BSPs are explained in our documents Yocto Reference Manual.
PHYTEC Documentation
PHYTEC will provide a variety of hardware and software documentation for all of our products. This includes any or all of the following:
...
Scroll Title | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Distro ampliphy-(vendor)-secure and ampliphy-(vendor)-provisioning
Note | ||
---|---|---|
| ||
Distro ampliphy-(vendor)-secure and ampliphy-(vendor)-provisioning are sample Yocto distros like ampliphy with additional security pre-configurations. Additional security measurements for production usage are necessary and depend on your threat model. PHYTEC services can support your implementation. |
...
Note | ||
---|---|---|
| ||
This example for filesystem encryption only works with eMMC, but not with NAND or NOR Flash. |
Provisioning your Device with Security in 5 steps
In only 5 steps, you can have a device with a secure boot, secure key storage, and secure storage.
You can download the phytec-provisioning-image and phytec-security-image for your board from our server https://download.phytec.de/Software/Linux/
or check out the code with a script from our git server:
Code Block |
---|
host$ mkdir ~/yocto host$ cd ~/yocto host$ wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux host$ chmod +x phyLinux host$ ./phyLinux init |
Initialize your Provisioning SD-Card
- Copy the phytec-provisioning-image.rootfs.sdcard to an SD card
- Resize the second partition "root" with GParted to a minimum of 3 Gbyte
- Copy the necessary images to the partition "root"
- a device with eMMC: copy the phytec-security-image.rootfs.sdcard and phytec-security-image.tar.gz to the SD card partition "root"
- a device with NAND: copy the phytec-simple-fitimage, device tree, and phytec-security-image.ubifs the SD card partition "root"
Activate Secure Boot on your Device
Please follow the instructions in the chapter Activate Secure Boot
Flash the eMMC with the phytec-security-image
Anchor | ||||
---|---|---|---|---|
|
- Set Bootjumper for booting from SD Card
- Plug-in power
- Boot to the Linux prompt and log in with the default password "root"
Mount the root partition from the SD card to the folder/media:
Scroll Title anchor i.MX 6/i.MX 6UL/i.MX 8M SD Card Folders title i.MX 6/i.MX 6UL/i.MX 8M SD Card Folders i.MX6 / i.MX6UL Mainline Kernel i.MX8M with NXP Kernel SD card Device: /dev/mmcblk0p2
SD card Device: /dev/mmcblk1p2
Code Block kernel$ mount <sd-card device> /media/
Use the phyprovisioning-install-emmc tool to flash the security image on the eMMC of your device:
Code Block kernel$ phyprovisioning-install-emmc -s /media/phytec-security-image.rootfs.sdcard -n
Everything is ready for the next step.
Init the Secure Key Storage
Please follow the instructions in the chapter Secure Key Storage "Secure Key Storage initialization with phySecureKeyStorage Tool"
Init the Secure Storage
By default, integrity and encryption are set in the distro ampliphy-(vendor)-secure. Therefore, the option intenc must be selected.
Please follow the instructions in the chapter Secure Storage "Secure Storage initialization with phySecureStorage Tool"
Secure Boot
Anchor | ||||
---|---|---|---|---|
|
Why Secure Boot?
Chain of Trust
Secure boot is used to ensure that only trustworthy, signed software can be executed on the controller. This is the first stage of the Chain-of-Trust. With the Chain-of-Trust, signed programs are always started by other previously verified programs. This ensures that even the end application is at the highest layer of trustworthiness.
...
Scroll Title | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Getting Started
NXP Controller
Anchor | ||||
---|---|---|---|---|
|
Information about Secure Boot on NXP Controller: https://www.nxp.com/search?keyword=AN4581
HABv4 RVT guidelines and recommendations: https://www.nxp.com/search?keyword=AN12263
- Code Signing Tools (CST) in version 3.3.2 or newer (install recipes are available in the BSP)
- Account required on NXP website: https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL_NEW&appType=file1&location=null&DOWNLOAD_ID=null
- Download the
cst-3.3.2.tgz
file - Place the
cst-3.3.2.tgz
file in the Yocto download folder
Enable Secure Boot Support in Yocto
Enable Secure Boot in your own distro
To enable secure boot, add the DISTRO_FEATURE
"secureboot" to your distro configuration file conf/distro/xyz.conf
:
...
Code Block |
---|
INHERIT += "secureboot" |
Configuration Class-Path to the Certificates
The path to the keys and certificates used for code-signing during the build process can be changed in the secureboot.bbclass
file:
...
For more information about keys and certificates, refer to Change PKI-Tree from phytec-dev-ca to the own PKI
Bootloader
i.MX6 and i.MX6UL/ULL with Barebox
Scroll Title | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
i.MX8M Series with u-boot
Scroll Title | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
Configuration Class - Signing Bootloader
All variables to adjust the bootloader signing process can be found in secureboot.bbclass
:
...
BOOTLOADER_SIGN: enable the bootloader signing
BOOTLOADER_SIGN_IMG_PATH, BOOTLOADER_SIGN_CSF_PATH, BOOTLOADER_SIGN_SRKFUSE_PATH: paths to the certificates and SRKFUSE-table required to sign the bootloader
Linux Kernel in the FIT-Image
Anchor | ||||
---|---|---|---|---|
|
FIT-Image Generation
First, add a FIT-Image recipe to your BSP layer. A possible location for this recipe could be recipes-images/fitimage/
...
slot type | |||
---|---|---|---|
kernel |
| ||
device tree |
| ||
fdt |
| ||
fdto |
| ||
fdtapply |
| ||
ramdisk |
| ||
bootscript |
| ||
tee |
|
With different slot classes for the kernel, devicetree, and ramdisk you can build very complex FIT-Images, which have support for different hardware boards or configurations.
Configuration Class - Signing FIT-Image
In the configuration class, secureboot.bbclass,
you can set all relevant variables for signing the FIT-Image.
...
FITIMAGE_SIGN
: Activation of the FIT-Image signingFITIMAGE_SIGNER
: Name of the FIT-Image signer, which is part of the FIT-Image certificateFITIMAGE_PUBKEY_SIGNATURE_PATH
: Automatically created manifest with a public key of the FITIMAGE_SIGN_KEY_PATH for storing in the bootloader device treeFITIMAGE_SIGN_KEY_PATH
: Path to the signing keyFITIMAGE_HASH
: Hash function for the FIT-Image artifacts. SHA1 and SHA256 are supportedFITIMAGE_SIGNATURE_ENCRYPTION
: Key type for FIT-Image certificate signing. RSA2048 and RSA4096 are supportedFITIMAGE_SIGNER_VERSION
: Version of the signer, which is part of the FIT-Image certificate
Start the Build Process
Refer to Start the Build.
...
- Barebox:
barebox-s.bin
,barebox-us.bin
- FIT-Image:
fitImage.fitimg
with the kernel, device tree, and ramdisk - FIT-Image manifest:
phytec-secureboot-ramdisk-fitimage-phyboard-mira-imx6-5.its
- RAM-disk:
phytec-secureboot-ramdisk-image-phyboard-mira-imx6-5.cpio.gz
- Root filesystem:
phytec-security-image-phyboard-mira-imx6-5.tar.gz
- eMMC image:
phytec-security-image-phyboard-mira-imx6-5.sdcard
withbarebox-s.bin
Booting and Updating the System
Refer to BSP Reference Manual for booting from different flashes and updating the software. Please use the signed bootloader images and Kernel or FIT-Images to program to the flash. The eMMC image is ready to use with a signed bootloader.
Activate Secure Boot on the Device
Anchor | ||||
---|---|---|---|---|
|
The final step to activate secure boot on your device is to burn the secure eFuse configuration.
...
When building the yocto-secure distro for the first time, the bootloader image is signed with PHYTEC's development keys. Yocto stores these development keys to yocto/phytec-dev-ca. Please refer to Change PKI-Tree from phytec-dev-ca to the own PKI.
For NXP i.MX Controllers with HABv4 (i.MX6, i.MX7, i.MX8M, i.MX8M mini, i.MX8M Plus), you will need the SRK_1_2_3_4_fuse.bin file. An example file is located in yocto/phytec-dev-ca/nxp_habv4_pki/crts/SRK_1_2_3_4_fuse.bin.
Note | ||
---|---|---|
| ||
Create and use your own keys and certificates for signing your images. Burn the right key into the Controller eFuse. Please refer to i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) Head. Create Your Own PKI Tree. |
eMMC Boot Partition to Enable Boot
Scroll Title | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||
|
Program the SRK eFuse
Scroll Title | |||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||
|
Lock the Device
Warning | ||
---|---|---|
| ||
This step is irreversible and could brick your device. Before closing the device:
|
...
Scroll Title | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
|
Burn SRK_LOCK
If you can successfully reboot after locking the device in the previous step, you should also burn the SRK_LOCK FUSE.
...
Scroll Title | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Next Steps after Lockdown
Warning | ||
---|---|---|
| ||
After you have closed the device, consider the following points with regard to how firmware authentication can potentially be skipped:
|
Revoke NXP SRK Key
Although securing the device involves programming the hash of four public keys into the eFuses, only one key (number 1 by default) is used in the secure boot process. If the key gets compromised, it can be revoked and a different key used.
...
Note | ||
---|---|---|
| ||
For more information, refer to https://www.nxp.com/docs/en/application-note/AN4581.pdf or NXP CST User's Guide. |
Secureboot on i.MX8M Series without FIT Images
In earlier releases, secureboot on the i.MX8M controller series signed the kernel and DTB. Support for authenticated ramdisks did not exist. We recommend using signed FIT images. Users who still wish to use that old mechanism should perform the following changes in their build configuration:
...
Rebuild u-boot-imx, imx-boot-phytec and linux-imx.
Kernel Module Signing
When the kernel module signing facility is enabled, Linux can enforce that only modules that have been signed with a specific key can be loaded. Keys with invalid signatures won't be allowed to load. This makes it harder for attackers to load malicious or manipulated modules.
...
Warning | ||
---|---|---|
| ||
By default, the kernel modules will be signed with PHYTEC's public, for example, the development key. Unless you create your own key, this feature does not offer any protection. |
Device Tree Overlay and Secure Boot
Device Tree overlays are device tree fragments that can be merged into a device tree during boot time. These are for example hardware descriptions of an expansion board. They are instead of being added to the device tree as an extra include, now applied as an overlay. They also may only contain setting a node's status depending on whether it is mounted or not.
Device Tree Overlay for i.MX6UL and i.MX6
Warning |
---|
The Device Tree Overlay support is generally deactivated and not supported for i.MX6UL and i.MX6 with Secure Boot in the security distro and image The new ADIN1300 Ethernet PHY is supported in the standard BSP as devicetree overlay for the phyBOARD-Mira and phyBOARD-Nunki. |
Device Tree Overlay for i.MX8M Series
Scroll Title | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||
|
...
Note | ||
---|---|---|
| ||
Please use Device Tree Overlay only in the development stage of your product. Create a final Device Tree for your device for the production phase. |
Deactivate Device Tree Overlay Support for i.MX8M Series
To disable the Device Tree Overlay support set the following variable in sources/meta-ampliphy/classes/secureboot.bbclass to true
...
Code Block |
---|
FITIMAGE_SLOTS ?= "kernel fdt fdto ramdisk" |
Secure Key Storage
Anchor | ||||
---|---|---|---|---|
|
A fundamental aspect of security is integrity and confidentiality. Many applications require an embedded device to keep sensitive data. The standard solution to this problem is to use encryption to protect the data and ensure that only authorized users have access to the encryption key. When a user interacts directly with a system, the encryption key can be protected with a password, pin code, or fingerprint that is provided by the user. However, many embedded devices work without user interaction, so this is not an option in those cases.
...
Machines built with the MACHINE_FEATURE have all necessary prerequisites enabled.
Supported Types of Secure Key Storage
NXP i.MX CAAM
Anchor | ||||
---|---|---|---|---|
|
The NXP i.MX6, i.MX6UL and i.MX8M series processors include hardware encryption through NXP's Cryptographic Accelerator and Assurance Module (CAAM, also known as SEC4). The CAAM combines functions to create a modular and scalable acceleration and assurance engine.
...
Scroll Title | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Prerequisites and Caveats
Secureboot is required for trusted CAAM Key blob functionality. If Secure Boot Keys are burned, the keys are locked. After a reset, the CAAM unit creates internal keys for the signing and encryption CAAM blobs. These keys are internal in the CAAM and can not be read out and overwritten.
Trusted Execution Environment: OP-TEE
OP-TEE is a Trusted Execution Environment (TEE) designed as a companion to a non-secure Linux kernel running on Arm; Cortex-A cores using the TrustZone technology.
...
PHYTEC includes OP-TEE only as a preview in ampliphy-secure. As an example application, once ready OP-TEE can then be used to protect the trusted key, as described in i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) Head. Testing OP-TEE.
OP-TEE is divided into the following components:
- OP-TEE kernel: The kernel acts as a secure world OS. This kernel is signed by HABv4.
- tee-supplicant: Helper daemon allowing OP-TEE to read/write from/to secure storage. In practice, this means OP-TEE will save encrypted and authenticated data in the filesystem.
- xtest: Utilities to test OP-TEE.
Prerequisites and Caveats
Secureboot and Hardware Unique Key
...
OP-TEE signs trusted applications (see https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html#trusted-application-private-public-keypair ) in order to ensure their authenticity and integrity. By default, OP-TEE uses a pre-generated key, which you must replace with your own before using OP-TEE in production.
Removing OP-TEE from your Build
If you wish to remove OP-TEE from your build, add the following code to your local.conf:
Code Block |
---|
MACHINE_FEATURES_remove = "optee" |
Testing OP-TEE
Anchor | ||||
---|---|---|---|---|
|
xtest
When OP-TEE is enabled during the build, the "xtest" utility will be shipped. Executing "xtest" will run a couple of tests supplied by the OP-TEE project to ensure it is working as intended.
...
The 0x5600000 address is the optee_core region. Access is currently being blocked by the TZASC policy set up by OP-TEE, which causes a "Bus error". The shared region, on the other hand, is accessible.
Trusted Platform Module (TPM) 2.0
The Trusted Platform Module (TPM) is an international standard for a secure cryptoprocessor, a dedicated microcontroller designed to secure hardware through integrated cryptographic keys.
The TPM 2.0 is:
...
- phyBOARD-Polis with NXP i.MX8M Mini
- phyBOARD-Pollux with NXP i.MX8M Plus
- phyGATE-Tauri-S with NXP i.MX6ULL (without NXP CAAM)
- phyGATE-Tauri-L wih NXP i.MX8M Mini
Initialization of TPM for filesystem Encryption
All commands are in the ramdisk userspace. Refer to First Boot or Recover a Device to stop the boot in the ramdisk.
Please use the tool phySecureKeyStorage Tool for the initialization of filesystem encryption if a trusted TPM key is initialized.
More information about Disk Encryption with TPM: https://tpm2-software.github.io/2020/04/13/Disk-Encryption.html
Initialization of TPM for Device Identification
Anchor | ||||
---|---|---|---|---|
|
In this example, the TPM will initialize and a self-signed certificate will be stored:
- First, you must create the secure storage trusted-tpm with the phySecureKeyStorage Tool
Code Block |
---|
kernel$ physecurekeystorage --newkeystorage trustedtpm |
...
Code Block |
---|
openssl_conf = openssl_init [openssl_init] engines = engine_section [engine_section] pkcs11 = pkcs11_section [pkcs11_section] engine_id = pkcs11 MODULE_PATH = /usr/lib/libtpm2_pkcs11.so.0 PIN=myuserpin init = 0 |
Kernel Key Retention Service for filesystem Encryption
"The Linux key-management facility is primarily a way for various kernel components to retain or cache security data, authentication keys, encryption keys, and other data in the kernel."
Linux kernel is a kernel’s facility for “password caching”, which stores them in a computer’s memory (RAM) during an active user’s/system session.
The Linux keyring accessing is via syscalls from the user space into the kernel space. Applications to access are keyctl
, systemd-ask-password and others.
...
Scroll Title | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
|
Secure Key Storage Initialization with phySecureKeyStorage Tool
Anchor | ||||
---|---|---|---|---|
|
The tool physecurekeystorage-install is part of the ramdisk userspace and included in the BSP from Yocto hardknott. Refer to First Boot or Recover a Device to stop the boot in the ramdisk. If the tool is not part of your BSP, then you can find the tool at: https://git.phytec.de/meta-ampliphy/tree/recipes-physecurity/secure-key-storage
...
Code Block |
---|
PHYTEC Install Script v1.6 for Secure Key Storage Usage: physecurekeystorage-install [PARAMETER] [ACTION] Example: physecurekeystorage-install --newkeystorage trustedtpm physecurekeystorage-install --deletekeystorage physecurekeystorage-install --loadkeystorage physecurekeystorage-install --pkcs11testkey One of the following action can be selected: -n | --newkeystorage <value> Create new Secure Key Storage trustedcaam (only NXP controller) trustedtee trustedtpm securecaam (black blob only NXP Vendor BSP) -d | --deletekeystorage Erase the existing Secure Key Storage -l | --loadkeystorage Load the existing Secure Key Storage -p | --pkcs11testkey Create an ECC testkey with user pin 1234 -h | --help This Help -v | --version The version of physecurekeystorage-install |
OpenSSL
OpenSSL is a robust, commercial-grade, full-featured software library for general-purpose cryptography and secure communication.
OpenSSL with TPM 2.0
The source/meta-ampliphy-/recipes-image/packagegroups/packagegroup-openssl-tpm2.bb makes the TPM 2.0 accessible via the standard OpenSSL API and command-line tools.
This package group uses the tpm2-tss-engine as a cryptographic engine for OpenSSL for Trusted Platform Module (TPM 2.0).
...
Cryptographic Token Interface PKCS#11
Also known as "Cryptoki". An API defining a generic interface to cryptographic tokens. Often used in single sign-on, public-key cryptography, and disk encryption systems. RSA Security has turned over further development of the PKCS #11 standard to the OASIS PKCS 11 Technical Committee.
...
- pkcs11-tool or p11kit with TPM 2.0:https://github.com/tpm2-software/tpm2-pkcs11
- OpenSSL with TPM 2.0: Initialize TPM for Device Identification
Secure Storage
Secure storage is a combination of the authenticated and encrypted filesystem that adds another layer of security to your product. It uses the kernel's cryptographic support to encrypt all the data you store in the root filesystem. Attempting to access this data without the correct encryption key returns random, meaningless bytes.
...
Note | ||
---|---|---|
| ||
|
Filesystem with Integrity vs Authenticated filesystem
The actual standard BSP includes integrity support with hash sha-256, which has protection against data error.
An authenticated file system should use HMAC with signed hashes, which have protection against device-turned-off data manipulation from attackers. For this variant, an additional symmetric key is necessary.
Requirements for Filesystem Encryption
- File integrity and encryption support for block devices (SD card, eMMC) or MTD device (NAND, NOR)
- Secure Key Storage to securely store the authentication and encryption key
- Secure Boot must be activated and the device must be locked for proper secure key storage.
- Protection Shield Level should be activated for access control on runtime.
Boot Process Flow
- bootloader verifies FIT-Image with linux-kernel image, device tree, and ramdisk before they are executed
- Linux kernel executes the ramdisk (read-only filesystem)
- The bootscript loads the authenticated encrypted filesystem encryption key with the CAAM|TEE|TPM unit in the RAM and encrypts the filesystem. After the encryption, the root filesystem will be switched and the boot process continues.
Starting the Build Process
Filesystem integrity and encryption are included in the DISTRO_FEATURE secureboot and securestorage.
...
Scroll Title | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||
|
Build All Necessary Images and eMMC Image
Code Block |
---|
host$ bitbake phytec-security-image |
When you change something on the boot init script, then you should, at minimum, clean the recipes for ramdisk and FIT-Image too. If you need a new eMMC image, then clean the image for encryption partition, too
Setup Secure Storage on your Device
The filesystem encryption ensures the target has a unique key or an equal key per device.
...
- The filesystem encryption key is generated and stored encrypted with CAAM, TEE, or TPM.
- Encryption is initialized.
- The partition is formatted.
- Data is copied to the encrypted partition.
1. First Boot
Anchor | ||||
---|---|---|---|---|
|
From a high-level point of view, an eMMC device is like an SD card. Therefore, it is possible to flash the image phytec-provisioning-image.sdcard from the Yocto build system directly to the SD card. The image contains the signed bootloader and signed FIT-Image with an initramfs.
...
- Boot the phytec-provisioning-image from the SD card
- Stop booting in the bootloader. The i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) Head Protection Shield Level low is in default with password: root
- The device stops with the following message because there is no encrypted key stored in the folder/secrets:
Code Block |
---|
Run /init as init process (none) login: |
The i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) Head Protection Shield Level low is in default with user: root and password: root
...
- If this is your first boot from the device and no image is on the eMMC, please Flash the eMMC with the phytec-security-image first.
2. Key Generation for Secure Storage
Anchor | ||||
---|---|---|---|---|
|
Please follow the instructions in the chapter Secure Key Storage initialization with phySecureKeyStorage Tool
3. Secure Storage Initialization with phySecureStorage Tool
Anchor | ||||
---|---|---|---|---|
|
The tool physecurestorage-install is part of the ramdisk userspace and included in the BSP from Yocto hardknott. Refer to First Boot or Recover a Device to stop the boot in the ramdisk. If the tool is not part of your BSP, then you can find the tool at: https://git.phytec.de/meta-ampliphy/tree/recipes-physecurity/secure-storage
...
- Restart the system. After a successful installation, the system will boot to the kernel login console.
Recover an Initialized Device
If your filesystem is damaged or the key blob is deleted, then you can reinstall the encrypted filesystem with the following options.
- Reinitialize your device with the phytec-provisioning-image from the SD card (i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) HeadBoot in ramdisk)
- Boot in rescue mode of the existing flash image with minimal tools support
...
Code Block |
---|
Run /init as init process (none) login: |
The i.MX 6 / i.MX 8 Security Manual (L-1004e.Ax) Head Protection Shield Level low is in default with user: root and password: root
Note | ||
---|---|---|
| ||
If there is no login in 60s, then the system goes to power off
|
Secure Update
Due to the connected nature of devices, security vulnerabilities are more widespread than ever before, and new threats are discovered by the security community daily. Security requirements change often, and it is therefore important to make sure your system is ready to be securely updated so new vulnerabilities can be patched or functionality can be added to the product. A secure update process involves more than safely updating a device. It also verifies that the delivered image is coming from a known source and that the image was not modified to introduce malware.
...
Warning | ||
---|---|---|
| ||
Before the version Yocto hardknott: After the RAUC update, the encrypted filesystem partition is NOT encrypted. The RAUC handler must be reworked to handle the updates for an encrypted filesystem. Additionally, the data in the RAUC bundles should be encrypted during the transition to the target with a different key. |
Access Control: Protection Shield Level
Anchor | ||||
---|---|---|---|---|
|
The DISTRO_FEATURE protection shield offers an easy way to switch between different protection levels. You can use the low protection level during your development and easily switch to a higher level for your final build when entering series production.
Password Protection in Protection Shield V1
The following table shows the different protection shield levels for password protection.
...
Warning | ||
---|---|---|
| ||
The variable PROTECTION_SHIELD_ROOT_PASSWORD is stored in your distro configuration file conf/distro/xyz.conf. Do not push this file to the git repository with your actual series password. |
User Role and Password Protection in Protection Shield V2
The phytec-security-image includes the phytec-example-users with the following configuration depending on the shield level. Most interfaces are in the group phyapix for access control.
Scroll Title | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||
|
Enable Protection Shield Support in Yocto
Enable Protection Shield in Your Own Distro
To enable the protection shield, add the DISTRO_FEATURE protectionshield to your distro configuration file conf/distro/xyz.conf. The variables PROTECTION_SHIELD_LEVEL and PROTECTION_SHIELD_ROOT_PASSWORD must be set:
Code Block |
---|
DISTRO_FEATURES += "protectionshield" PROTECTION_SHIELD_LEVEL = "shieldlow" #user root password for shield low and midle #password quality decide about the protection level PROTECTION_SHIELD_ROOT_PASSWORD ?= 'root' |
Enable Protection Shield Level in Your Kernel Image
To enable a protection shield in your Linux kernel image, you need to include recipes-images/images/security/setrootpassword.inc into your image recipe. For an example, please take a look at recipes-images/images/phytec-security
-image.bb included in ampliphy-secure.
If you use a ramdisk for your filesystem, you will need to include recipes-images/images/security/setrootpassword.inc into your ramdisk recipe, too. For an example, please take a look at recipes-images/images/phytec-secureboot-ramdisk-image.bb included in ampliphy-secure.
Hardening of the System
The DISTRO_FEATURE hardening activates the kernel reduction with deselect fragments. The name of the deselection variable is KERNEL_FEATURES_DESELECT.
...
Scroll Title | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||
|
Physical Security
To further protect your device, it is important to reduce attack vectors. Start by securing development features like JTAG and serial downloader. For activation or deactivation of controller features, is necessary to write and read eFuses.
Warning | ||
---|---|---|
| ||
The secure eFuse configuration can only be written once and is irreversible. |
Secure JTAG
Anchor | ||||
---|---|---|---|---|
|
Most embedded devices provide a JTAG interface for debugging purposes. However, if left unprotected, this interface can become an important attack vector on the systems in series production. The i.MX6 series System JTAG Controller (SJC) allows you to regulate JTAG access with three security modes using OTP (One Time Programmable) eFuses:
...
Additional information about JTAG Security can be found here: https://www.nxp.com/docs/en/application-note/AN4686.pdf
Disabled Debugging Mode
Set JTAG to "Disabled debugging" mode:
Scroll Title | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Secure JTAG Mode
Set JTAG to "Secure" mode as an example for i.MX6/i.MX6UL.
- Generate a secret response key
You can choose between Identical Response Keys on each device or unique response keys for every device
Code Block host$ cat /dev/random | tr -dc a-f0-9 | head -c${1:-14} | sed 's,^\([[:xdigit:]]\{6\}\)\([[:xdigit:]]\{8\}\),0x00\1 0x\2,g'
You will receive, for example:
Code Block 0x00edcba9 0x87654321
Write secret response key:
Scroll Title anchor Secret Response Key title Secret Response Key i.MX6* with barebox i.MX8MM Code Block barebox$ mw -l -d /dev/imx-ocotp 0x80 0x87654321 barebox$ mw -l -d /dev/imx-ocotp 0x81 0x00edcba9
Code Block uboot$ fuse prog 8 0 0x87654321 uboot$ fuse prog 8 1 0x00edcba9
Lock access to secret response key:
Scroll Title anchor Secret Response Key title Secret Response Key i.MX6* with barebox i.MX8MM Code Block barebox$ mw -l -d /dev/imx-ocotp 0x00 0x0040
Code Block uboot$ fuse prog 0 0 0x400
Set Secure JTAG mode:
Scroll Title anchor Secure JTAG Mode title Secure JTAG Mode i.MX6* with barebox i.MX8MM Code Block barebox$ mw -l -d /dev/imx-ocotp 0x18 0x400000
Code Block uboot$ fuse prog 0 0 0x400000
Disable JTAG Mode
Scroll Title | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Disable HAB JTAG Enabling
When JTAG is set in "Secure", an option to enable HAB JTAG DEBUG becomes available. By writing '1' to HAB_JDE (HAB JTAG DEBUG ENABLE) bit in the e-fuse controller module, the JTAG is opened, regardless of its security mode. If this feature is not required, it is highly recommended this be disabled.
...
Scroll Title | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Disable Serial Downloader
Anchor | ||||
---|---|---|---|---|
|
The i.MX6, i.MX6UL and i.MX8M series Controller supports the burning of different eFuse to disable the USB Serial Download Protocol (SDP) and Force Internal Boot Only to enhance device security.
Note | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||
i.MX6 and i.MX6UL: i.MX & Vybrid Security Vulnerability Errata - ERR010872, ERR010873 Below is a list of PHYTEC Products and variants that include the controller version with the feature for Disable Serial Downloader and Force Internal Boot:
For phyFLEX-i.MX6 and phyCARD-i.MX6 support, ask your sales contact. |
Disable SDP Mode Completely
Disabling the serial download support is recommended for security-enabled configurations:
Scroll Title | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Disable Read Access in SDP
Disabling only read access via SDP. Writing will still be possible.
Scroll Title | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Force Internal Boot
Ensure the device always boots in INTERNAL BOOT mode, ignoring BOOT_MODE pins. This setting is recommended for security-enabled configurations. This feature is supported in the listed PHYTEC products.
Scroll Title | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Disable Boot from External Memory
By writing to the DIR_BT_DIS FUSE, we can disable boot from external memory.
i.MX6 / i.MX6UL | i.MX8M | ||||
---|---|---|---|---|---|
|
|
Keys and Certificates Management
Public Key Infrastructure Tree (PKI tree)
To use a secure boot with a signed bootloader and a signed kernel image, several keys and certificates are required to sign the images. The key and certificate creation is a manual process and the public key infrastructure (PKI) tree must be in place before you start your build. This BSP includes the PHYTECD development pki-tree as an example. You are obligated to create your own pki-tree with your own keys and certificates.
Note | ||
---|---|---|
| ||
It is highly recommended to use different keys for different parts of your system to avoid a single point of failure regarding your security concept. |
PHYTEC Development Keys (phytec-dev-ca)
The included phytec-dev-ca example consists of a self-signed main-ca and three derived sub-ca's for bootloader, Fit-Image, and RAUC updates.
...
Warning | ||
---|---|---|
| ||
|
NXP HABv4 Key Structure
The NXP HABv4 Key structure is for signing the bootloader and FIT-Image, which is verified from the ROM bootloader of the NXP controller with the HABv4 module. The i.MX6, i.MX6UL, i.MX7, i.MX8M, and i.MX8M Mini includes a HABv4 module for secure boot.
- CA (Certification Authority): This certificate is used to sign the SRK keys and establish the authority of other keys. There is only one CA certificate per PKI tree. This certificate is never used on the target and has no requirements. An existing certificate can be used as CA during the generation of all these keys. The rest of the keys and certificates are always generated and have special requirements, as they are directly used on the target.
- SRK (Super Root Keys): This certificate is used to sign the CSF and IMG certificates. There are up to four SRK certificates per PKI tree (each one is used to sign one CSF and one IMG certificate). See revoke a key for more information on having multiple SRK certificates.
- CSF (Command Sequence File): This certificate is used to validate the CSF region.
- IMG: This certificate is used to validate the bootloader or FIT-Image data.
Create Your Own PKI Tree
Anchor | ||||
---|---|---|---|---|
|
Please create your PKI offline with a separate system. For example, boot a read-only system from USB which you only use to create the PKI. The phytec-dev-ca is created with XCA from https://hohnstaedt.de/xca/, but you can use any other tool, too.
...
For creation, the SRK table and SRK Fuses from the SRK certificates are scripts in the NXP CST archive in the folder cst-3.3.1/code/hab_srktool_scripts,
which used the cst-3.3.1/linux64/bin/srktool.
Change PKI-Tree from phytec-dev-ca to Your Own PKI
Anchor | ||||
---|---|---|---|---|
|
In the configuration class sources/meta-ampliphy/classes/secureboot.bbclass
, the path to your PKI tree is initially defined:
...
Code Block |
---|
host$ bitbake -c cleanall phytec-secureboot-ramdisk-fitimage host$ bitbake -c cleanall phytec-security-bundle host$ bitbake -c cleanall phytec-security-image |
Encryption Keys
Scroll Title | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
Using HSM (PKCS#11 tokens) to Sign Images
Note | ||
---|---|---|
| ||
Support is experimental as, at this point, it relies on the PIN value being specified in the PKCS#11 URI. |
...
Note | ||
---|---|---|
| ||
A number of pitfalls are available in PKCS#11 which may allow a private key to leave the token. https://link.springer.com/chapter/10.1007/978-3-540-45238-6_32 |
Getting started with SoftHSM
During development, SoftHSM can be used to get started with PKCS#11 before you move on to using a hardware token. To make this step easier, PHYTEC ships a softhsm "token" dir with phytec's development keys already imported. Please see phytec-dev-ca/pkcs11/softhsm for more information on how to make use of this directory.
Signing Secure Boot Images
A guideline on how to sign images using the CST tool and PKCS#11 has been made available by NXP: https://www.nxp.com/webapp/Download?colCode=AN12812
...
Note | ||
---|---|---|
| ||
Usage without p11-kit-proxy If you don't have p11-kit-proxy or don't want to use it, the path to the PKCS#11 module must be specified in the PKCS11_MODULE_PATH variable in your build/conf/local.conf file. For example: PKCS11_MODULE_PATH="/var/lib/softhsm/libsofthsm2.so" |
Signing Kernel Modules
Kernel modules can also be signed using HSMs. Keep in mind that signing the modules takes time. Therefore, the build time for the kernel will likely vastly increase when employing PKCS#11 Hardware tokens. This largely depends on the processing power of your token, but generally smart card-like tokens will lead to a significant increase.
Code Block |
---|
MODSIGN_KEY="pkcs11:token=CST-PHYTECDEVCA;pin-value=12345678;object=kernel-modsign" # For your own keys, set this to the cert file belonging to the private key supplied by PKCS#11 # MODSIGN_CERT="/path/to/cert.pem" |
Signing RAUC Bundles
RAUC will use the libp11-proxy library. To override it, set the path to your library in the RAUC_PKCS11_MODULE var in the build/conf/local.conf file. You must set the PKCS#11 URI for the key and cert:
...
More information about RAUC and PKCS#11 can be found here: https://rauc.readthedocs.io/en/latest/advanced.html?highlight=pkcs11#pkcs-11-support
PKCS#11 from Inside Docker
If you are using Docker to build images, tokens plugged into your machine can't be accessed right away. You must allow the Docker container access to your device, as described below.
...
Your container must have all the libraries and drivers installed/configured that are necessary to use your token.
Security Vulnerabilities
The used software can be affected by security vulnerabilities. A security vulnerability generally is a bug in software code that could allow an attacker to gain control of a system. It is essential to check the software regularly against published security flaws (Common Vulnerabilities and Exposures).
Revision History
Date | Version Number | Changes to the Manual |
---|---|---|
11.05.2020 | L-1004e.A0 | 1st Release |
03.8.2021 | L-1004e.A1 | Information added for:
|
13.12.2021 | L-1004e.A2 |
|
01.07.2022 | L-1004e.A3 |
|
17.10.2022 | L-1004e.A4 |
|
08.11.2022 | L-1004e.A5 |
|
...