--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ # Index of the key location in the SRK table to be installed
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # Key used to authenticate the CSF data
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Install Key]
+ # Key slot index used to authenticate the key to be installed
+ Verification index = 0
+ # Target key slot in HAB key store where key will be installed
+ Target index = 2
+ # Key to install
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ # Key slot index used to authenticate the image data
+ Verification index = 2
+ # Authenticate Start Address, Offset, Length and file
+ Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
+ 0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
+ 0x00910000 0x0F56C8 0x09139 "flash.bin", \
+ 0xFE000000 0x0FE804 0x4D268 "flash.bin", \
+ 0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ Verification index = 0
+ Target index = 2
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-enc.bin"
+
+[Install Secret Key]
+ # Install the blob
+ Verification Index = 0
+ Target Index = 0
+ Key = "dek_fit.bin"
+ Key Length = 128
+ # Fixed address defined in imx-mkimage project in iMX8M/soc.mak file
+ # DEK_BLOB_LOAD_ADDR = 0x40400000
+ Blob Address = 0x40400000
+
+[Decrypt Data]
+ # The decrypt data command below causes CST to modify the input
+ # file and encrypt the specified block of data. This image file
+ # is a copy of the file used for the authentication command above
+ Verification Index = 0
+ Mac Bytes = 16
+ Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
+ 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ Verification index = 0
+ Target index = 2
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin", \
+ 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
+ 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+
+[Install Secret Key]
+ # Install the blob
+ Verification Index = 0
+ Target Index = 0
+ Key = "dek_fit_dummy.bin"
+ Key Length = 128
+ # Fixed address defined in imx-mkimage project in iMX8M/soc.mak file
+ # DEK_BLOB_LOAD_ADDR = 0x40400000
+ Blob Address = 0x40400000
+
+[Decrypt Data]
+ # The decrypt data command below causes CST to modify the input
+ # file and encrypt the specified block of data. This image file
+ # is a copy of the file used for the authentication command above
+ Verification Index = 0
+ Mac Bytes = 16
+ Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
+ 0x920000 0x113540 0xA160 "flash-spl-fit-enc-dummy.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
+
--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ # Index of the key location in the SRK table to be installed
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # Key used to authenticate the CSF data
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ # Leave Job Ring and DECO master ID registers Unlocked
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ # Key slot index used to authenticate the key to be installed
+ Verification index = 0
+ # Target key slot in HAB key store where key will be installed
+ Target index = 2
+ # Key to install
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ # Key slot index used to authenticate the image data
+ Verification index = 2
+ # Authenticate Start Address, Offset, Length and file
+ Blocks = 0x7e0fc0 0x1a000 0x2a600 "flash.bin"
--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ Verification index = 0
+ Target index = 2
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ Blocks = 0x7e0fc0 0x0 0x40 "flash.bin"
+
+[Install Secret Key]
+ # Install the blob
+ Verification Index = 0
+ Target Index = 0
+ Key = "dek_spl.bin"
+ Key Length = 128
+ # Authenticate Start Address + SPL & DDR FW image length + CSF Padding
+ # 0x7E0FC0 + 0x2c400 + 0x2000
+ Blob Address = 0x80F3C0
+
+[Decrypt Data]
+ # The decrypt data command below causes CST to modify the input
+ # file and encrypt the specified block of data. This image file
+ # is a copy of the file used for the authentication command above
+ Verification Index = 0
+ Mac Bytes = 16
+ # Start Address = Start Address + SPL header = 0x7E0FC0 + 0x40 = 0x7E1000
+ # Offset = Image offset (image_off) = 0x40
+ # Decrypt size = Image length - SPL header = 0x2c400 - 0x40 = 0x2C3C0
+ Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc.bin"
--- /dev/null
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ Verification index = 0
+ Target index = 2
+ File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ Blocks = 0x7E0FC0 0x0 0x2C400 "flash-spl-enc.bin"
+
+[Install Secret Key]
+ # Install the blob
+ Verification Index = 0
+ Target Index = 0
+ Key = "dek_spl_dummy.bin"
+ Key Length = 128
+ # Authenticate Start Address + Image length + CSF Padding
+ # 0x7E0FC0 + 0x2c400 + 0x2000
+ Blob Address = 0x80F3C0
+
+[Decrypt Data]
+ # The decrypt data command below causes CST to modify the input
+ # file and encrypt the specified block of data. This image file
+ # is a copy of the file used for the authentication command above
+ Verification Index = 0
+ Mac Bytes = 16
+ Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc-dummy.bin"
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- # Index of the key location in the SRK table to be installed
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- # Key used to authenticate the CSF data
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Install Key]
- # Key slot index used to authenticate the key to be installed
- Verification index = 0
- # Target key slot in HAB key store where key will be installed
- Target index = 2
- # Key to install
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- # Key slot index used to authenticate the image data
- Verification index = 2
- # Authenticate Start Address, Offset, Length and file
- Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
- 0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
- 0x00910000 0x0F56C8 0x09139 "flash.bin", \
- 0xFE000000 0x0FE804 0x4D268 "flash.bin", \
- 0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Unlock]
- Engine = CAAM
- Features = MID
-
-[Install Key]
- Verification index = 0
- Target index = 2
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- Verification index = 2
- Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-enc.bin"
-
-[Install Secret Key]
- # Install the blob
- Verification Index = 0
- Target Index = 0
- Key = "dek_fit.bin"
- Key Length = 128
- # Fixed address defined in imx-mkimage project in iMX8M/soc.mak file
- # DEK_BLOB_LOAD_ADDR = 0x40400000
- Blob Address = 0x40400000
-
-[Decrypt Data]
- # The decrypt data command below causes CST to modify the input
- # file and encrypt the specified block of data. This image file
- # is a copy of the file used for the authentication command above
- Verification Index = 0
- Mac Bytes = 16
- Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
- 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Unlock]
- Engine = CAAM
- Features = MID
-
-[Install Key]
- Verification index = 0
- Target index = 2
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- Verification index = 2
- Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin", \
- 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
- 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
-
-[Install Secret Key]
- # Install the blob
- Verification Index = 0
- Target Index = 0
- Key = "dek_fit_dummy.bin"
- Key Length = 128
- # Fixed address defined in imx-mkimage project in iMX8M/soc.mak file
- # DEK_BLOB_LOAD_ADDR = 0x40400000
- Blob Address = 0x40400000
-
-[Decrypt Data]
- # The decrypt data command below causes CST to modify the input
- # file and encrypt the specified block of data. This image file
- # is a copy of the file used for the authentication command above
- Verification Index = 0
- Mac Bytes = 16
- Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
- 0x920000 0x113540 0xA160 "flash-spl-fit-enc-dummy.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
-
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- # Index of the key location in the SRK table to be installed
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- # Key used to authenticate the CSF data
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Unlock]
- # Leave Job Ring and DECO master ID registers Unlocked
- Engine = CAAM
- Features = MID
-
-[Install Key]
- # Key slot index used to authenticate the key to be installed
- Verification index = 0
- # Target key slot in HAB key store where key will be installed
- Target index = 2
- # Key to install
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- # Key slot index used to authenticate the image data
- Verification index = 2
- # Authenticate Start Address, Offset, Length and file
- Blocks = 0x7e0fc0 0x1a000 0x2a600 "flash.bin"
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Unlock]
- Engine = CAAM
- Features = MID
-
-[Install Key]
- Verification index = 0
- Target index = 2
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- Verification index = 2
- Blocks = 0x7e0fc0 0x0 0x40 "flash.bin"
-
-[Install Secret Key]
- # Install the blob
- Verification Index = 0
- Target Index = 0
- Key = "dek_spl.bin"
- Key Length = 128
- # Authenticate Start Address + SPL & DDR FW image length + CSF Padding
- # 0x7E0FC0 + 0x2c400 + 0x2000
- Blob Address = 0x80F3C0
-
-[Decrypt Data]
- # The decrypt data command below causes CST to modify the input
- # file and encrypt the specified block of data. This image file
- # is a copy of the file used for the authentication command above
- Verification Index = 0
- Mac Bytes = 16
- # Start Address = Start Address + SPL header = 0x7E0FC0 + 0x40 = 0x7E1000
- # Offset = Image offset (image_off) = 0x40
- # Decrypt size = Image length - SPL header = 0x2c400 - 0x40 = 0x2C3C0
- Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc.bin"
+++ /dev/null
-[Header]
- Version = 4.3
- Hash Algorithm = sha256
- Engine = CAAM
- Engine Configuration = 0
- Certificate Format = X509
- Signature Format = CMS
-
-[Install SRK]
- File = "../crts/SRK_1_2_3_4_table.bin"
- Source index = 0
-
-[Install CSFK]
- File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate CSF]
-
-[Unlock]
- Engine = CAAM
- Features = MID
-
-[Install Key]
- Verification index = 0
- Target index = 2
- File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
-
-[Authenticate Data]
- Verification index = 2
- Blocks = 0x7E0FC0 0x0 0x2C400 "flash-spl-enc.bin"
-
-[Install Secret Key]
- # Install the blob
- Verification Index = 0
- Target Index = 0
- Key = "dek_spl_dummy.bin"
- Key Length = 128
- # Authenticate Start Address + Image length + CSF Padding
- # 0x7E0FC0 + 0x2c400 + 0x2000
- Blob Address = 0x80F3C0
-
-[Decrypt Data]
- # The decrypt data command below causes CST to modify the input
- # file and encrypt the specified block of data. This image file
- # is a copy of the file used for the authentication command above
- Verification Index = 0
- Mac Bytes = 16
- Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc-dummy.bin"
--- /dev/null
+ +======================================================+
+ + i.MX8M family Encrypted Boot guide using HABv4 +
+ +======================================================+
+
+1. HABv4 Encrypted Boot process
+-------------------------------
+
+This document describes a step-by-step procedure on how to encrypt and sign a
+bootloader image for i.MX8M family devices. It is assumed that the reader is
+familiar with basic HAB concepts and has already closed the device, step-by-step
+procedure can be found in mx8m_secure_boot.txt guide.
+
+Details about encrypted boot can be found in application note AN12056[1] and
+in the introduction_habv4.txt document.
+
+The steps described in this document were based in i.MX8MM device, the same
+concept can be applied to other i.MX8M family devices.
+
+1.1 Understanding the encrypted flash.bin image layout
+------------------------------------------------------
+
+As described in mx8m_secure_boot.txt guide a single binary is used to boot the
+device, the imx-mkimage tool combines all the input images in a FIT structure,
+generating a flash.bin binary.
+
+The encrypted boot image requires a DEK (Data Encryption Key) blob on each time
+HABv4 is used to decrypt an image. The DEK blob is used as a security layer to
+wrap and store the DEK off-chip using the OTPMK which is unique per device.
+More details can be found in AN12056 application note.
+
+The diagram below illustrates an encrypted flash.bin image layout:
+
+ +-----------------------------+
+ | |
+ | *Signed HDMI/DP FW |
+ | |
+ +-----------------------------+
+ | Padding |
+ ------------------ +-----------------------------+ --------
+ ^ | IVT - SPL | ^
+ Signed | ------- +-----------------------------+ |
+ Data | Enc ^ | u-boot-spl.bin | |
+ | Data | | + | | SPL
+ v v | DDR FW | | Image
+ ------------------ +-----------------------------+ |
+ | CSF - SPL + DDR FW | v
+ +-----------------------------+ --------
+ | DEK Blob |
+ +-----------------------------+
+ | Padding |
+ ------- +-----------------------------+ --------
+ Signed ^ | FDT - FIT | ^
+ Data | +-----------------------------+ |
+ v | IVT - FIT | |
+ ------- +-----------------------------+ |
+ | CSF - FIT | |
+ ------------------ +-----------------------------+ |
+ ^ | u-boot-nodtb.bin | | FIT
+ | +-----------------------------+ | Image
+ Signed and | | u-boot.dtb | |
+ Encrypted | +-----------------------------+ |
+ Data | | bl31.bin (ATF) | |
+ | +-----------------------------+ |
+ v | OP-TEE | |
+ ------------------ +-----------------------------+ |
+ | DEK Blob | v
+ +-----------------------------+ --------
+ * Only supported on i.MX8M series
+
+1.2 Enabling the encrypted boot support in U-Boot
+--------------------------------------------------
+
+For deploying an encrypted boot image additional U-Boot tools are needed,
+please be sure to have the following features enabled, this can be achieved
+by following one of the methods below:
+
+- Defconfig
+
+ CONFIG_IMX_HAB=y
+ CONFIG_FAT_WRITE=y
+ CONFIG_CMD_DEKBLOB=y
+ CONFIG_IMX_OPTEE_DEK_ENCAP=y
+ CONFIG_CMD_PRIBLOB=y
+
+- Kconfig
+
+ ARM architecture -> Support i.MX HAB features
+ ARM architecture -> Support the 'dek_blob' command
+ ARM architecture -> Support the set_priblob_bitfield command
+ File systems -> Enable FAT filesystem support-> Enable FAT filesystem
+ write support
+
+1.3 Enabling the encrypted boot support in CST
+-----------------------------------------------
+
+The encryption feature is not enabled by default in Code Signing tools (CST).
+The CST backend must be recompiled, execute the following commands to enable
+encryption support in CST:
+
+ $ sudo apt-get install libssl-dev openssl
+ $ cd <CST install directory>/code/back_end/src
+ $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
+ -lfrontend -lcrypto
+ $ cp cst_encrypted ../../../linux64/bin/
+
+1.4 Building OP-TEE and ATF to support DEK blob tool
+-----------------------------------------------------
+
+The DEK blob must be created by a software running in Arm TrustZone Secure
+World, the CAAM block takes into consideration the TrustZone configuration
+when encapsulating the DEK and the resulting blob can be only decapsulated
+by a SW running in the same configuration. As ROM code is running in ARM
+TrustZone secure world we must encapsulate the blobs using OP-TEE.
+
+- Building ATF to support OP-TEE:
+
+ $ make PLAT=<SoC Name> SPD=opteed bl31
+
+- Building OP-TEE to support DEK blob encapsulation:
+
+ $ CFG_NXPCRYPT=y CFG_GEN_DEK_BLOB=y source ./scripts/nxp_build.sh <Board Name>
+
+* OP-TEE debug logs can be enabled by adding CFG_TEE_CORE_LOG_LEVEL=4 in
+ command line above.
+
+1.5 Preparing the fit image
+----------------------------
+
+As explained in mx8m_secure_boot.txt document the imx-mkimage project is used to
+combine all the images in a single flash.bin binary.
+
+Copy all the binaries generated (U-Boot images, bl31.bin, tee.bin and Firmware)
+into iMX8M directory and run the following commands according to the target
+device:
+
+- Create a dummy DEK blob:
+
+ $ dd if=/dev/zero of=iMX8M/dek_blob_fit_dummy.bin bs=96 count=1 && sync
+
+- Assembly flash.bin binary:
+
+ $ make SOC=<SoC Name> flash_spl_uboot
+
+The mkimage log will be used during the encrypted boot procedure to create the
+Command Sequence File (CSF):
+
+- imx-mkimage build log:
+
+ Loader IMAGE:
+ header_image_off 0x0
+ dcd_off 0x0
+ image_off 0x40
+ csf_off 0x2c400
+ spl hab block: 0x7e0fc0 0x0 0x2c400
+
+ Second Loader IMAGE:
+ sld_header_off 0x57c00
+ sld_csf_off 0x58c20
+ sld hab block: 0x401fcdc0 0x57c00 0x1020
+
+- Additional HAB information is provided by running the following command:
+
+ $ make SOC=<SoC Name> print_fit_hab
+
+ ./../scripts/pad_image.sh bl31.bin
+ ./../scripts/pad_image.sh u-boot-nodtb.bin fsl-imx8mm-evk.dtb
+ TEE_LOAD_ADDR=0xbe000000 ATF_LOAD_ADDR=0x00920000 VERSION=v1 \
+ ./print_fit_hab.sh 0x60000 fsl-imx8mm-evk.dtb
+ 0x40200000 0x5AC00 0xB0318
+ 0x402B0318 0x10AF18 0x8628
+ 0x920000 0x113540 0xA160
+ 0xBE000000 0x11D6A0 0x48520
+
+1.6 Creating the CSF description file for SPL + DDR FW image
+-------------------------------------------------------------
+
+The CSF contains all the commands that the ROM executes during the secure boot.
+These commands instruct the HAB on which memory areas of the image to
+authenticate and/or decrypt, which keys to install, use, etc...
+
+CSF examples for encrypted boot are available under
+doc/imx/hab/habv4/csf_examples/ directory.
+
+With current CST implementation is not possible to encrypt and sign an image
+at the same time, hence two CSF files are required on each time HAB is used.
+
+1.6.1 csf_spl_enc.txt
+----------------------
+
+The first CSF is used to encrypt the SPL and DDR FW images and generate the
+dek_spl.bin file. The Authenticate Data command has to cover only the image
+header and two commands have to be added to encrypt the image.
+
+- Add the Authenticate Data command to only cover SPL IVT and boot data:
+
+ Blocks = 0x7E0FC0 0x0 0x40 "flash.bin"
+
+- Add the Install Secret Key command to generate the dek_spl.bin file and
+ install the blob. The Blob Address depends on your image layout and can
+ be calculated as following:
+
+ Key = "dek_spl.bin"
+ Blob Address = Authenticate Start Address + Image length + CSF Padding
+ = 0x7E0FC0 + 0x2c400 + 0x2000 = 0x80F3C0
+
+- Add the Decrypt Data command to encrypt the file. As SPL image header
+ cannot be encrypted we need to calculate the Block as following:
+
+ Start Address = Start Address + SPL header = 0x7E0FC0 + 0x40 = 0x7E1000
+ Offset = Image offset (image_off) = 0x40
+ Decrypt size = Image length - SPL header = 0x2C400 - 0x40 = 0x2C3C0
+
+ Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc.bin"
+
+1.6.2 csf_spl_sign_enc.txt
+---------------------------
+
+The second CSF is used to sign the encrypted SPL image previously generated
+(flash-spl-enc.bin).
+
+- The Authenticate Data command should cover the entire SPL and DDR FW image,
+ the file parameter is the encrypted image flash-spl-enc.bin:
+
+ Blocks = 0x7E0FC0 0x0 0x2C400 "flash-spl-enc.bin"
+
+- Add the Install Secret Key command to generate a dummy DEK blob file,
+ the blob address should be the same as used in csf_spl_enc.txt:
+
+ Key = "dek_spl_dummy.bin"
+
+- Add the Decrypt Data command to encrypt the file. As image was encrypted
+ in CSF above we need to encrypt a dummy file, the block addresses should be
+ the same as used in csf_spl_enc.txt:
+
+ Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc-dummy.bin"
+
+1.7 Encrypting and signing the SPL + DDR FW image
+--------------------------------------------------
+
+The CST is used to encrypt the image and regenerate a random DEK. During this
+step two CSF binaries are generated but only one will be included in final
+image.
+
+- Encrypt the SPL + DDR FW image:
+
+ $ cp flash.bin flash-spl-enc.bin
+ $ ./cst_encrypted -i csf_spl_enc.txt -o csf_spl_enc.bin
+
+- Sign the encrypted SPL + DDR FW image:
+
+ $ cp flash-spl-enc.bin flash-spl-enc-dummy.bin
+ $ ./cst_encrypted -i csf_spl_sign_enc.txt -o csf_spl_sign_enc.bin
+
+1.7.1 Create final CSF binary for SPL + DDR FW image
+-----------------------------------------------------
+
+As only one CSF binary will be included in final image it's necessary to
+swap Nonce/MAC from csf_spl_enc.bin to csf_spl_sign_enc.bin.
+
+- Calculate Nonce/MAC size based on MAC bytes value in CSF:
+
+ Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
+ = 12 + 16 + 8 = 36 bytes
+
+- Calculate Nonce/MAC offset in CSF:
+
+ MAC offset = csf_spl_enc.bin size - Nonce/MAC size
+ = 3980 - 36 = 3944 Bytes
+
+- Extract Nonce/MAC from csf_spl_enc.bin:
+
+ $ dd if=csf_spl_enc.bin of=noncemac.bin bs=1 skip=3944 count=36
+
+- Replace the MAC of csf_spl_sign_enc with the one extracted above:
+
+ $ dd if=noncemac.bin of=csf_spl_sign_enc.bin bs=1 seek=3944 count=36
+
+1.8 Creating the CSF description file for FIT image
+----------------------------------------------------
+
+Similar to SPL image two CSF files are required encrypt and sign the FIT
+image.
+
+Please note that the steps below are using the flash-spl-enc.bin image created
+in steps above.
+
+1.8.1 csf_fit_enc.txt
+----------------------
+
+The first CSF is used to encrypt the FIT image and generate the dek_fit.bin
+file.
+
+- Modify the Authenticate Data command to only cover FIT image FDT header:
+
+ Blocks = 0x401FCDC0 0x57C00 0x1020 "flash-spl-enc.bin"
+
+- Add the Install Secret Key command to generate the dek_fit.bin file and
+ install the blob. The Blob Address is a fixed address defined in imx-mkimage
+ project in iMX8M/soc.mak file:
+
+ iMX8M/soc.mak:
+ DEK_BLOB_LOAD_ADDR = 0x40400000
+
+ Key = "dek_fit.bin"
+ Blob Address = 0x40400000
+
+- Add the Decrypt Data command to encrypt the file.
+
+ The CST can only encrypt images that are 16 bytes aligned, as u-boot-nodtb.bin
+ and u-boot.dtb are together 16 bytes aligned we should consider the first two
+ lines provided in print_fit_hab as a single block.
+
+ imx-mkimage output:
+
+ 0x40200000 0x5AC00 0xB0318 ──┬── Total length = 0xB0318 + 0x8628 = 0xB8940
+ 0x402B0318 0x10AF18 0x8628 ──┘
+ 0x920000 0x113540 0xA160
+ 0xBE000000 0x11D6A0 0x48520
+
+ Decrypt data in csf_fit_enc.txt:
+
+ Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
+ 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+
+1.8.2 csf_fit_sign_enc.txt
+---------------------------
+
+The second CSF is used to sign the encrypted FIT image previously generated
+(flash-spl-fit-enc.bin).
+
+- The Authenticate Data command should cover the entire FIT image,
+ the file parameter is the encrypted FIT image flash-spl-fit-enc.bin:
+
+ Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin"
+ 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
+ 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+
+
+- Add the Install Secret Key command to generate a dummy DEK blob file,
+ the blob address should be the same as used in csf_spl_enc.txt:
+
+ Key = "dek_fit_dummy.bin"
+
+- Add the Decrypt Data command to encrypt the file. As image was encrypted
+ in CSF above we need to encrypt a dummy file, the block address should be
+ the same as used in csf_spl_enc.txt:
+
+ Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
+ 0x920000 0x113540 0xA160"flash-spl-fit-enc-dummy.bin", \
+ 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
+
+1.9 Encrypting and signing the FIT image
+-----------------------------------------
+
+The CST is used to encrypt the image and regenerate a random DEK. During this
+step two CSF binaries are generated but only one will be included in final
+image.
+
+- Encrypt the FIT image:
+
+ $ cp flash-spl-enc.bin flash-spl-fit-enc.bin
+ $ ./cst_encrypted -i csf_fit_enc.txt -o csf_fit_enc.bin
+
+- Sign the encrypted FIT image:
+
+ $ cp flash-spl-fit-enc.bin flash-spl-fit-enc-dummy.bin
+ $ ./cst_encrypted -i csf_fit_sign_enc.txt -o csf_fit_sign_enc.bin
+
+1.9.1 Create final CSF binary for FIT image
+-----------------------------------------------------
+
+As only one CSF binary will be included in final image it's necessary to swap
+Nonce/MAC from csf_fit_enc.bin to csf_fit_sign_enc.bin.
+
+- Calculate Nonce/MAC size based on MAC bytes value in CSF:
+
+ Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
+ = 12 + 16 + 8 = 36 bytes
+
+- Calculate Nonce/MAC offset in csf_fit_enc.bin:
+
+ MAC offset = csf_fit_enc.bin size - Nonce/MAC size
+ = 3996 - 36 = 3960 Bytes
+
+- Extract Nonce/MAC from csf_fit_enc.bin:
+
+ $ dd if=csf_fit_enc.bin of=noncemac.bin bs=1 skip=3960 count=36
+
+- Calculate Nonce/MAC offset in csf_fit_sign_enc.bin:
+
+ MAC offset = csf_fit_enc.bin size - Nonce/MAC size
+ = 4020 - 36 = 3984 Bytes
+
+- Replace the MAC of csf_fit_sign_enc.bin with the one extracted above:
+
+ $ dd if=noncemac.bin of=csf_fit_sign_enc.bin bs=1 seek=3984 count=36
+
+1.10 Generate the DEK Blob
+---------------------------
+
+The DEK must be encapsulated into a CAAM blob so it can be included into
+the final encrypted binary. The U-Boot provides a tool called dek_blob
+which is calling the CAAM implementation included in OP-TEE.
+
+Copy the dek_spl.bin and dek_fit.bin in SDCard FAT partition and run
+the following commands from U-Boot prompt:
+
+ => mmc list
+ FSL_SDHC: 1 (SD)
+ FSL_SDHC: 2
+ => fatload mmc 1:1 0x40400000 dek_spl.bin
+ => dek_blob 0x40400000 0x40401000 128
+ => fatwrite mmc 1:1 0x40401000 dek_spl_blob.bin 0x48
+ => fatload mmc 1:1 0x40402000 dek_fit.bin
+ => dek_blob 0x40402000 0x40403000 128
+ => fatwrite mmc 1:1 0x40403000 dek_fit_blob.bin 0x48
+
+In host PC copy the generated dek_spl_blob.bin and dek_fit_blob.bin to the
+CST directory.
+
+1.11 Assembly the encrypted image
+----------------------------------
+
+The CSF binaries generated in the steps above have to be inserted into the
+encrypted image.
+
+The CSF offsets can be obtained from the flash.bin build log:
+
+- SPL CSF offset:
+
+ csf_off 0x2c400
+
+- FIT CSF offset:
+
+ sld_csf_off 0x58c20
+
+The encrypted flash.bin image can be then assembled:
+
+- Create a flash-spl-fit-enc.bin copy:
+
+ $ cp flash-spl-fit-enc.bin encrypted-flash.bin
+
+1.11.1 Insert SPL CSF and DEK blob
+-----------------------------------
+
+- Insert csf_spl_sign_enc.bin in encrypted-flash.bin at 0x2c400 offset:
+
+ $ dd if=csf_spl_sign_enc.bin of=encrypted-flash.bin seek=$((0x2c400)) bs=1 conv=notrunc
+
+- Insert dek_spl_blob.bin in encrypted-flash.bin at 0x2c400 + 0x2000 offset:
+
+ $ dd if=dek_spl_blob.bin of=encrypted-flash.bin seek=$((0x2e400)) bs=1 conv=notrunc
+
+1.11.2 Insert FIT CSF and DEK blob
+-----------------------------------
+
+- Insert csf_fit_sign_enc.bin in encrypted-flash.bin at 0x58c20 offset:
+
+ $ dd if=csf_fit_sign_enc.bin of=encrypted-flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
+
+- The DEK blob must be inserted in last image entry on FIT image, the last line
+ provided by print_fit_hab taget log target can be used:
+
+ 0x40200000 0x5AC00 0xB0318
+ 0x402B0318 0x10AF18 0x8628
+ 0x920000 0x113540 0xA160
+ 0xBE000000 0x11D6A0 0x48520 -> Last line in print_fit_hab log
+
+- Insert dek_fit_blob.bin encrypted-flash.bin at 0x11D6A0 + 0x48520 offset:
+
+ $ dd if=dek_fit_blob.bin of=encrypted-flash.bin seek=$((0x165BC0)) bs=1 conv=notrunc
+
+1.11.3 Flash encrypted boot image
+-----------------------------------
+
+- Flash encrypted image in SDCard:
+
+ $ sudo dd if=encrypted-flash.bin of=/dev/sd<x> bs=1K seek=33* && sync
+ * Offset in i.MX8MN device is 32K.
+
+2.0 Setting the PRIBLOB in CAAM SCFGR register
+-----------------------------------------------
+
+It is highly recommended to advance the PRIBLOB field in CAAM SCFGR register to
+0x3, a command is available in U-Boot that should be called after all images in
+boot flow has been decrypted by HAB:
+
+ => set_priblob_bitfield
+
+The PRIBLOB configuration ensures cryptographic separation of private blob
+types avoiding any modification or replacement of DEK blobs. Newly created
+blobs will be incompatible with blobs required to decrypt an encrypted boot
+image. When the HAB later executes the command to decrypt the DEK, an
+incompatible DEK blob will be detected and cause an error. A substitute
+encrypted boot image will not be decrypted, and will not be executed.
+
+References:
+[1] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1
+++ /dev/null
- +======================================================+
- + i.MX8M, i.MX8MM Encrypted Boot guide using HABv4 +
- +======================================================+
-
-1. HABv4 Encrypted Boot process
--------------------------------
-
-This document describes a step-by-step procedure on how to encrypt and sign a
-bootloader image for i.MX8M, i.MX8MM, i.MX8MN family devices. It is assumed
-that the reader is familiar with basic HAB concepts and has already closed
-the device, step-by-step procedure can be found in mx8m_mx8mm_secure_boot.txt
-guide.
-
-Details about encrypted boot can be found in application note AN12056[1] and
-in the introduction_habv4.txt document.
-
-The steps described in this document were based in i.MX8MM device, the same
-concept can be applied to i.MX8M and i.MX8MN family devices.
-
-1.1 Understanding the encrypted flash.bin image layout
-------------------------------------------------------
-
-As described in mx8m_mx8mm_secure_boot.txt guide a single binary is used
-to boot the device, the imx-mkimage tool combines all the input images in
-a FIT structure, generating a flash.bin binary.
-
-The encrypted boot image requires a DEK (Data Encryption Key) blob on each time
-HABv4 is used to decrypt an image. The DEK blob is used as a security layer to
-wrap and store the DEK off-chip using the OTPMK which is unique per device.
-More details can be found in AN12056 application note.
-
-The diagram below illustrates an encrypted flash.bin image layout:
-
- +-----------------------------+
- | |
- | *Signed HDMI/DP FW |
- | |
- +-----------------------------+
- | Padding |
- ------------------ +-----------------------------+ --------
- ^ | IVT - SPL | ^
- Signed | ------- +-----------------------------+ |
- Data | Enc ^ | u-boot-spl.bin | |
- | Data | | + | | SPL
- v v | DDR FW | | Image
- ------------------ +-----------------------------+ |
- | CSF - SPL + DDR FW | v
- +-----------------------------+ --------
- | DEK Blob |
- +-----------------------------+
- | Padding |
- ------- +-----------------------------+ --------
- Signed ^ | FDT - FIT | ^
- Data | +-----------------------------+ |
- v | IVT - FIT | |
- ------- +-----------------------------+ |
- | CSF - FIT | |
- ------------------ +-----------------------------+ |
- ^ | u-boot-nodtb.bin | | FIT
- | +-----------------------------+ | Image
- Signed and | | u-boot.dtb | |
- Encrypted | +-----------------------------+ |
- Data | | bl31.bin (ATF) | |
- | +-----------------------------+ |
- v | OP-TEE | |
- ------------------ +-----------------------------+ |
- | DEK Blob | v
- +-----------------------------+ --------
- * Only supported on i.MX8M series
-
-1.2 Enabling the encrypted boot support in U-Boot
---------------------------------------------------
-
-For deploying an encrypted boot image additional U-Boot tools are needed,
-please be sure to have the following features enabled, this can be achieved
-by following one of the methods below:
-
-- Defconfig
-
- CONFIG_SECURE_BOOT=y
- CONFIG_FAT_WRITE=y
- CONFIG_CMD_DEKBLOB=y
- CONFIG_IMX_OPTEE_DEK_ENCAP=y
- CONFIG_CMD_PRIBLOB=y
-
-- Kconfig
-
- ARM architecture -> Support i.MX HAB features
- ARM architecture -> Support the 'dek_blob' command
- ARM architecture -> Support the set_priblob_bitfield command
- File systems -> Enable FAT filesystem support-> Enable FAT filesystem
- write support
-
-1.3 Enabling the encrypted boot support in CST
------------------------------------------------
-
-The encryption feature is not enabled by default in Code Signing tools (CST).
-The CST backend must be recompiled, execute the following commands to enable
-encryption support in CST:
-
- $ sudo apt-get install libssl-dev openssl
- $ cd <CST install directory>/code/back_end/src
- $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
- -lfrontend -lcrypto
- $ cp cst_encrypted ../../../linux64/bin/
-
-1.4 Building OP-TEE and ATF to support DEK blob tool
------------------------------------------------------
-
-The DEK blob must be created by a software running in Arm TrustZone Secure
-World, the CAAM block takes into consideration the TrustZone configuration
-when encapsulating the DEK and the resulting blob can be only decapsulated
-by a SW running in the same configuration. As ROM code is running in ARM
-TrustZone secure world we must encapsulate the blobs using OP-TEE.
-
-- Building ATF to support OP-TEE:
-
- $ make PLAT=<SoC Name> SPD=opteed bl31
-
-- Building OP-TEE to support DEK blob encapsulation:
-
- $ CFG_NXPCRYPT=y CFG_GEN_DEK_BLOB=y source ./scripts/nxp_build.sh <Board Name>
-
-* OP-TEE debug logs can be enabled by adding CFG_TEE_CORE_LOG_LEVEL=4 in
- command line above.
-
-1.5 Preparing the fit image
-----------------------------
-
-As explained in mx8m_mx8mm_secure_boot.txt document the imx-mkimage project is
-used to combine all the images in a single flash.bin binary.
-
-Copy all the binaries generated (U-Boot images, bl31.bin, tee.bin and Firmware)
-into iMX8M directory and run the following commands according to the target
-device:
-
-- Create a dummy DEK blob:
-
- $ dd if=/dev/zero of=iMX8M/dek_blob_fit_dummy.bin bs=96 count=1 && sync
-
-- Assembly flash.bin binary:
-
- $ make SOC=<SoC Name> flash_spl_uboot
-
-The mkimage log will be used during the encrypted boot procedure to create the
-Command Sequence File (CSF):
-
-- imx-mkimage build log:
-
- Loader IMAGE:
- header_image_off 0x0
- dcd_off 0x0
- image_off 0x40
- csf_off 0x2c400
- spl hab block: 0x7e0fc0 0x0 0x2c400
-
- Second Loader IMAGE:
- sld_header_off 0x57c00
- sld_csf_off 0x58c20
- sld hab block: 0x401fcdc0 0x57c00 0x1020
-
-- Additional HAB information is provided by running the following command:
-
- $ make SOC=<SoC Name> print_fit_hab
-
- ./../scripts/pad_image.sh bl31.bin
- ./../scripts/pad_image.sh u-boot-nodtb.bin fsl-imx8mm-evk.dtb
- TEE_LOAD_ADDR=0xbe000000 ATF_LOAD_ADDR=0x00920000 VERSION=v1 \
- ./print_fit_hab.sh 0x60000 fsl-imx8mm-evk.dtb
- 0x40200000 0x5AC00 0xB0318
- 0x402B0318 0x10AF18 0x8628
- 0x920000 0x113540 0xA160
- 0xBE000000 0x11D6A0 0x48520
-
-1.6 Creating the CSF description file for SPL + DDR FW image
--------------------------------------------------------------
-
-The CSF contains all the commands that the ROM executes during the secure boot.
-These commands instruct the HAB on which memory areas of the image to
-authenticate and/or decrypt, which keys to install, use, etc...
-
-CSF examples for encrypted boot are available under
-doc/imx/hab/habv4/csf_examples/ directory.
-
-With current CST implementation is not possible to encrypt and sign an image
-at the same time, hence two CSF files are required on each time HAB is used.
-
-1.6.1 csf_spl_enc.txt
-----------------------
-
-The first CSF is used to encrypt the SPL and DDR FW images and generate the
-dek_spl.bin file. The Authenticate Data command has to cover only the image
-header and two commands have to be added to encrypt the image.
-
-- Add the Authenticate Data command to only cover SPL IVT and boot data:
-
- Blocks = 0x7E0FC0 0x0 0x40 "flash.bin"
-
-- Add the Install Secret Key command to generate the dek_spl.bin file and
- install the blob. The Blob Address depends on your image layout and can
- be calculated as following:
-
- Key = "dek_spl.bin"
- Blob Address = Authenticate Start Address + Image length + CSF Padding
- = 0x7E0FC0 + 0x2c400 + 0x2000 = 0x80F3C0
-
-- Add the Decrypt Data command to encrypt the file. As SPL image header
- cannot be encrypted we need to calculate the Block as following:
-
- Start Address = Start Address + SPL header = 0x7E0FC0 + 0x40 = 0x7E1000
- Offset = Image offset (image_off) = 0x40
- Decrypt size = Image length - SPL header = 0x2C400 - 0x40 = 0x2C3C0
-
- Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc.bin"
-
-1.6.2 csf_spl_sign_enc.txt
----------------------------
-
-The second CSF is used to sign the encrypted SPL image previously generated
-(flash-spl-enc.bin).
-
-- The Authenticate Data command should cover the entire SPL and DDR FW image,
- the file parameter is the encrypted image flash-spl-enc.bin:
-
- Blocks = 0x7E0FC0 0x0 0x2C400 "flash-spl-enc.bin"
-
-- Add the Install Secret Key command to generate a dummy DEK blob file,
- the blob address should be the same as used in csf_spl_enc.txt:
-
- Key = "dek_spl_dummy.bin"
-
-- Add the Decrypt Data command to encrypt the file. As image was encrypted
- in CSF above we need to encrypt a dummy file, the block addresses should be
- the same as used in csf_spl_enc.txt:
-
- Blocks = 0x7E1000 0x40 0x2C3C0 "flash-spl-enc-dummy.bin"
-
-1.7 Encrypting and signing the SPL + DDR FW image
---------------------------------------------------
-
-The CST is used to encrypt the image and regenerate a random DEK. During this
-step two CSF binaries are generated but only one will be included in final
-image.
-
-- Encrypt the SPL + DDR FW image:
-
- $ cp flash.bin flash-spl-enc.bin
- $ ./cst_encrypted -i csf_spl_enc.txt -o csf_spl_enc.bin
-
-- Sign the encrypted SPL + DDR FW image:
-
- $ cp flash-spl-enc.bin flash-spl-enc-dummy.bin
- $ ./cst_encrypted -i csf_spl_sign_enc.txt -o csf_spl_sign_enc.bin
-
-1.7.1 Create final CSF binary for SPL + DDR FW image
------------------------------------------------------
-
-As only one CSF binary will be included in final image it's necessary to
-swap Nonce/MAC from csf_spl_enc.bin to csf_spl_sign_enc.bin.
-
-- Calculate Nonce/MAC size based on MAC bytes value in CSF:
-
- Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
- = 12 + 16 + 8 = 36 bytes
-
-- Calculate Nonce/MAC offset in CSF:
-
- MAC offset = csf_spl_enc.bin size - Nonce/MAC size
- = 3980 - 36 = 3944 Bytes
-
-- Extract Nonce/MAC from csf_spl_enc.bin:
-
- $ dd if=csf_spl_enc.bin of=noncemac.bin bs=1 skip=3944 count=36
-
-- Replace the MAC of csf_spl_sign_enc with the one extracted above:
-
- $ dd if=noncemac.bin of=csf_spl_sign_enc.bin bs=1 seek=3944 count=36
-
-1.8 Creating the CSF description file for FIT image
-----------------------------------------------------
-
-Similar to SPL image two CSF files are required encrypt and sign the FIT
-image.
-
-Please note that the steps below are using the flash-spl-enc.bin image created
-in steps above.
-
-1.8.1 csf_fit_enc.txt
-----------------------
-
-The first CSF is used to encrypt the FIT image and generate the dek_fit.bin
-file.
-
-- Modify the Authenticate Data command to only cover FIT image FDT header:
-
- Blocks = 0x401FCDC0 0x57C00 0x1020 "flash-spl-enc.bin"
-
-- Add the Install Secret Key command to generate the dek_fit.bin file and
- install the blob. The Blob Address is a fixed address defined in imx-mkimage
- project in iMX8M/soc.mak file:
-
- iMX8M/soc.mak:
- DEK_BLOB_LOAD_ADDR = 0x40400000
-
- Key = "dek_fit.bin"
- Blob Address = 0x40400000
-
-- Add the Decrypt Data command to encrypt the file.
-
- The CST can only encrypt images that are 16 bytes aligned, as u-boot-nodtb.bin
- and u-boot.dtb are together 16 bytes aligned we should consider the first two
- lines provided in print_fit_hab as a single block.
-
- imx-mkimage output:
-
- 0x40200000 0x5AC00 0xB0318 ──┬── Total length = 0xB0318 + 0x8628 = 0xB8940
- 0x402B0318 0x10AF18 0x8628 ──┘
- 0x920000 0x113540 0xA160
- 0xBE000000 0x11D6A0 0x48520
-
- Decrypt data in csf_fit_enc.txt:
-
- Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
- 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
-
-1.8.2 csf_fit_sign_enc.txt
----------------------------
-
-The second CSF is used to sign the encrypted FIT image previously generated
-(flash-spl-fit-enc.bin).
-
-- The Authenticate Data command should cover the entire FIT image,
- the file parameter is the encrypted FIT image flash-spl-fit-enc.bin:
-
- Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin"
- 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
- 0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
-
-
-- Add the Install Secret Key command to generate a dummy DEK blob file,
- the blob address should be the same as used in csf_spl_enc.txt:
-
- Key = "dek_fit_dummy.bin"
-
-- Add the Decrypt Data command to encrypt the file. As image was encrypted
- in CSF above we need to encrypt a dummy file, the block address should be
- the same as used in csf_spl_enc.txt:
-
- Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
- 0x920000 0x113540 0xA160"flash-spl-fit-enc-dummy.bin", \
- 0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
-
-1.9 Encrypting and signing the FIT image
------------------------------------------
-
-The CST is used to encrypt the image and regenerate a random DEK. During this
-step two CSF binaries are generated but only one will be included in final
-image.
-
-- Encrypt the FIT image:
-
- $ cp flash-spl-enc.bin flash-spl-fit-enc.bin
- $ ./cst_encrypted -i csf_fit_enc.txt -o csf_fit_enc.bin
-
-- Sign the encrypted FIT image:
-
- $ cp flash-spl-fit-enc.bin flash-spl-fit-enc-dummy.bin
- $ ./cst_encrypted -i csf_fit_sign_enc.txt -o csf_fit_sign_enc.bin
-
-1.9.1 Create final CSF binary for FIT image
------------------------------------------------------
-
-As only one CSF binary will be included in final image it's necessary to swap
-Nonce/MAC from csf_fit_enc.bin to csf_fit_sign_enc.bin.
-
-- Calculate Nonce/MAC size based on MAC bytes value in CSF:
-
- Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
- = 12 + 16 + 8 = 36 bytes
-
-- Calculate Nonce/MAC offset in csf_fit_enc.bin:
-
- MAC offset = csf_fit_enc.bin size - Nonce/MAC size
- = 3996 - 36 = 3960 Bytes
-
-- Extract Nonce/MAC from csf_fit_enc.bin:
-
- $ dd if=csf_fit_enc.bin of=noncemac.bin bs=1 skip=3960 count=36
-
-- Calculate Nonce/MAC offset in csf_fit_sign_enc.bin:
-
- MAC offset = csf_fit_enc.bin size - Nonce/MAC size
- = 4020 - 36 = 3984 Bytes
-
-- Replace the MAC of csf_fit_sign_enc.bin with the one extracted above:
-
- $ dd if=noncemac.bin of=csf_fit_sign_enc.bin bs=1 seek=3984 count=36
-
-1.10 Generate the DEK Blob
----------------------------
-
-The DEK must be encapsulated into a CAAM blob so it can be included into
-the final encrypted binary. The U-Boot provides a tool called dek_blob
-which is calling the CAAM implementation included in OP-TEE.
-
-Copy the dek_spl.bin and dek_fit.bin in SDCard FAT partition and run
-the following commands from U-Boot prompt:
-
- => mmc list
- FSL_SDHC: 1 (SD)
- FSL_SDHC: 2
- => fatload mmc 1:1 0x40400000 dek_spl.bin
- => dek_blob 0x40400000 0x40401000 128
- => fatwrite mmc 1:1 0x40401000 dek_spl_blob.bin 0x48
- => fatload mmc 1:1 0x40402000 dek_fit.bin
- => dek_blob 0x40402000 0x40403000 128
- => fatwrite mmc 1:1 0x40403000 dek_fit_blob.bin 0x48
-
-In host PC copy the generated dek_spl_blob.bin and dek_fit_blob.bin to the
-CST directory.
-
-1.11 Assembly the encrypted image
-----------------------------------
-
-The CSF binaries generated in the steps above have to be inserted into the
-encrypted image.
-
-The CSF offsets can be obtained from the flash.bin build log:
-
-- SPL CSF offset:
-
- csf_off 0x2c400
-
-- FIT CSF offset:
-
- sld_csf_off 0x58c20
-
-The encrypted flash.bin image can be then assembled:
-
-- Create a flash-spl-fit-enc.bin copy:
-
- $ cp flash-spl-fit-enc.bin encrypted-flash.bin
-
-1.11.1 Insert SPL CSF and DEK blob
------------------------------------
-
-- Insert csf_spl_sign_enc.bin in encrypted-flash.bin at 0x2c400 offset:
-
- $ dd if=csf_spl_sign_enc.bin of=encrypted-flash.bin seek=$((0x2c400)) bs=1 conv=notrunc
-
-- Insert dek_spl_blob.bin in encrypted-flash.bin at 0x2c400 + 0x2000 offset:
-
- $ dd if=dek_spl_blob.bin of=encrypted-flash.bin seek=$((0x2e400)) bs=1 conv=notrunc
-
-1.11.2 Insert FIT CSF and DEK blob
------------------------------------
-
-- Insert csf_fit_sign_enc.bin in encrypted-flash.bin at 0x58c20 offset:
-
- $ dd if=csf_fit_sign_enc.bin of=encrypted-flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
-
-- The DEK blob must be inserted in last image entry on FIT image, the last line
- provided by print_fit_hab taget log target can be used:
-
- 0x40200000 0x5AC00 0xB0318
- 0x402B0318 0x10AF18 0x8628
- 0x920000 0x113540 0xA160
- 0xBE000000 0x11D6A0 0x48520 -> Last line in print_fit_hab log
-
-- Insert dek_fit_blob.bin encrypted-flash.bin at 0x11D6A0 + 0x48520 offset:
-
- $ dd if=dek_fit_blob.bin of=encrypted-flash.bin seek=$((0x165BC0)) bs=1 conv=notrunc
-
-1.11.3 Flash encrypted boot image
------------------------------------
-
-- Flash encrypted image in SDCard:
-
- $ sudo dd if=encrypted-flash.bin of=/dev/sd<x> bs=1K seek=33* && sync
- * Offset in i.MX8MN device is 32K.
-
-2.0 Setting the PRIBLOB in CAAM SCFGR register
------------------------------------------------
-
-It is highly recommended to advance the PRIBLOB field in CAAM SCFGR register to
-0x3, a command is available in U-Boot that should be called after all images in
-boot flow has been decrypted by HAB:
-
- => set_priblob_bitfield
-
-The PRIBLOB configuration ensures cryptographic separation of private blob
-types avoiding any modification or replacement of DEK blobs. Newly created
-blobs will be incompatible with blobs required to decrypt an encrypted boot
-image. When the HAB later executes the command to decrypt the DEK, an
-incompatible DEK blob will be detected and cause an error. A substitute
-encrypted boot image will not be decrypted, and will not be executed.
-
-References:
-[1] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1
+++ /dev/null
- +=======================================================+
- + i.MX8M, i.MX8MM Secure Boot guide using HABv4 +
- +=======================================================+
-
-1. HABv4 secure boot process
------------------------------
-
-This document describes a step-by-step procedure on how to sign and securely
-boot a bootloader image on i.MX8M and i.MX8MM devices. It is assumed that
-the reader is familiar with basic HAB concepts and with the PKI tree generation.
-
-Details about HAB can be found in the application note AN4581[1] and in the
-introduction_habv4.txt document.
-
-1.1 Understanding the i.MX8M and i.MX8MM flash.bin image layout
-----------------------------------------------------------------
-
-Due to the new the architecture, multiple firmwares and softwares are required
-to boot i.MX8M and i.MX8MM devices. In order to store all the images in a
-single binary the FIT (Flattened Image Tree) image structure is used.
-
-The final image is generated by the imx-mkimage project, the tool combines all
-the input images in a FIT structure, generating a flash.bin image with an
-appropriate IVT set.
-
-For a secure boot process users should ensure all images included in flash.bin
-file are covered by a digital signature.
-
-- The diagram below illustrate a signed flash.bin image layout:
-
- +-----------------------------+
- | |
- | *Signed HDMI/DP FW |
- | |
- +-----------------------------+
- | Padding |
- ------- +-----------------------------+ --------
- ^ | IVT - SPL | ^
- Signed | +-----------------------------+ |
- Data | | u-boot-spl.bin | |
- | | + | | SPL
- v | DDR FW | | Image
- ------- +-----------------------------+ |
- | CSF - SPL + DDR FW | v
- +-----------------------------+ --------
- | Padding |
- ------- +-----------------------------+ --------
- Signed ^ | FDT - FIT | ^
- Data | +-----------------------------+ |
- v | IVT - FIT | |
- ------- +-----------------------------+ |
- | CSF - FIT | |
- ------- +-----------------------------+ | FIT
- ^ | u-boot-nodtb.bin | | Image
- | +-----------------------------+ |
- Signed | | OP-TEE (Optional) | |
- Data | +-----------------------------+ |
- | | bl31.bin (ATF) | |
- | +-----------------------------+ |
- v | u-boot.dtb | v
- ------- +-----------------------------+ --------
- * Only supported on i.MX8M series
-
-The boot flow on i.MX8M and i.MX8MM devices are slightly different when compared
-with i.MX6 and i.MX7 series, the diagram below illustrate the boot sequence
-overview:
-
-- i.MX8M and i.MX8MM devices boot flow:
-
- Secure World Non-Secure World
- |
- |
- +------------+ +------------+ |
- | SPL | | i.MX 8M/MM | |
- | + | ---> | ROM | |
- | DDR FW | | + HAB | |
- +------------+ +------------+ |
- | |
- v |
- +------------+ |
- | *Signed | |
- | HDMI/DP FW | |
- +------------+ |
- | |
- v |
- +------------+ +------------+ |
- | FIT Image: | | SPL | |
- | ATF + TEE | ---> | + | |
- | + U-Boot | | DDR FW | | +-----------+
- +------------+ +------------+ | | Linux |
- | | +-----------+
- v | ^
- +------------+ | | +-------+
- | ARM | | +-----------+ | Linux |
- | Trusted | ----+---> | U-Boot | <--- | + |
- | Firmware | | +-----------+ | DTB |
- +------------+ | +-------+
- | |
- v |
- +----------+ |
- | **OP-TEE | |
- +----------+ |
- * Only supported on i.MX8M series
- ** Optional
-
-On i.MX8M devices the HDMI firmware or DisplayPort firmware are the first image
-to boot on the device. These firmwares are signed and distributed by NXP, and
-are always authenticated regardless of security configuration. In case not
-required by the application the HDMI or DisplayPort controllers can be disabled
-by eFuses and the firmwares are not required anymore.
-
-The next images are not signed by NXP and users should follow the signing
-procedure as described in this document.
-
-The Second Program Loader (SPL) and DDR firmware are loaded and authenticated
-by the ROM code, these images are executed in the internal RAM and responsible
-for initializing essential features such as DDR, UART, PMIC and clock
-enablement.
-
-Once the DDR is available, the SPL code loads all the images included in the
-FIT structure to their specific execution addresses, the HAB APIs are called
-to extend the root of trust, authenticating the U-Boot, ARM trusted firmware
-(ATF) and OP-TEE (If included).
-
-The root of trust can be extended again at U-Boot level to authenticate Kernel
-and M4 images.
-
-1.2 Enabling the secure boot support in U-Boot
------------------------------------------------
-
-The first step is to generate an U-Boot image supporting the HAB features,
-similar to i.MX6 and i.MX7 series the U-Boot provides extra functions for
-HAB, such as the HAB status logs retrievement through the hab_status command
-and support to extend the root of trust.
-
-The support is enabled by adding the CONFIG_SECURE_BOOT to the build
-configuration:
-
-- Defconfig:
-
- CONFIG_SECURE_BOOT=y
-
-- Kconfig:
-
- ARM architecture -> Support i.MX HAB features
-
-1.3 Preparing the fit image
-----------------------------
-
-The imx-mkimage project is used to combines all the images in a single
-flash.bin binary, the following files are required:
-
-- U-Boot:
- u-boot-nodtb.bin
- u-boot-spl.bin
- U-Boot DTB file (e.g. fsl-imx8mq-evk.dtb)
-
-- ATF image:
- bl31.bin
-
-- DDR firmware:
- lpddr4_pmu_train_1d_dmem.bin
- lpddr4_pmu_train_1d_imem.bin
- lpddr4_pmu_train_2d_dmem.bin
- lpddr4_pmu_train_2d_imem.bin
-
-- HDMI firmware (Only in i.MX8M):
- signed_hdmi_imx8m.bin
-
-- DisplayPort firmware (Only in i.MX8M):
- signed_dp_imx8m.bin
-
-- OP-TEE (Optional):
- tee.bin
-
-The procedure to build ATF and download the firmwares are out of the scope
-of this document, please refer to the Linux BSP Release Notes and AN12212[2]
-for further details.
-
-Copy all files to iMX8M directory and run the following command according to
-the target device, on this example we are building a HDMI target and also
-including the OP-TEE binary:
-
-- Assembly flash.bin binary:
-
- $ make SOC=<SoC Name> flash_hdmi_spl_uboot
-
-The mkimage log can be used to calculate the authenticate image command
-parameters and CSF offsets:
-
-- imx-mkimage build log:
-
- Loader IMAGE:
- header_image_off 0x1a000
- dcd_off 0x0
- image_off 0x1a040
- csf_off 0x44600
- spl hab block: 0x7e0fd0 0x1a000 0x2e600
-
- Second Loader IMAGE:
- sld_header_off 0x57c00
- sld_csf_off 0x58c20
- sld hab block: 0x401fcdc0 0x57c00 0x1020
-
-Additional HAB information is provided by running the following command:
-
-- Printing HAB FIT information:
-
- $ make SOC=<SoC Name> print_fit_hab
-
- TEE_LOAD_ADDR=0xfe000000 ATF_LOAD_ADDR=0x00910000 ./print_fit_hab.sh \
- 0x60000 fsl-imx8mq-evk.dtb
- 0x40200000 0x5AC00 0x9AAC8
- 0x910000 0xF56C8 0x9139
- 0xFE000000 0xFE804 0x4D268
- 0x4029AAC8 0x14BA6C 0x6DCF
-
-1.4 Creating the CSF description file
---------------------------------------
-
-The CSF contains all the commands that the ROM executes during the secure
-boot. These commands instruct the HAB code on which memory areas of the image
-to authenticate, which keys to install, use and etc.
-
-CSF examples are available under doc/imx/hab/habv4/csf_examples/ directory.
-
-As explained in sections above the SPL is first authenticated by the ROM code
-and the root of trust is extended to the FIT image, hence two CSF files are
-necessary to completely sign an flash.bin image.
-
-The build log provided by imx-mkimage can be used to define the "Authenticate
-Data" parameter in CSF.
-
-- SPL "Authenticate Data" addresses in flash.bin build log:
-
- spl hab block: 0x7e0fd0 0x1a000 0x2e600
-
-- "Authenticate Data" command in csf_spl.txt file:
-
- Blocks = 0x7e0fd0 0x1a000 0x2e600 "flash.bin"
-
-- FIT image "Authenticate Data" addresses in flash.bin build log:
-
- sld hab block: 0x401fcdc0 0x57c00 0x1020
-
-- FIT image "Authenticate Data" addresses in print_fit_hab build log:
-
- 0x40200000 0x5AC00 0x9AAC8
- 0x910000 0xF56C8 0x9139
- 0xFE000000 0xFE804 0x4D268
- 0x4029AAC8 0x14BA6C 0x6DCF
-
-- "Authenticate Data" command in csf_fit.txt file:
-
- Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
- 0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
- 0x00910000 0x0F56C8 0x09139 "flash.bin", \
- 0xFE000000 0x0FE804 0x4D268 "flash.bin", \
- 0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
-
-1.4.1 Avoiding Kernel crash in closed devices
-----------------------------------------------
-
-For devices prior to HAB v4.4.0, the HAB code locks the Job Ring and DECO
-master ID registers in closed configuration. In case the user specific
-application requires any changes in CAAM MID registers it's necessary to
-add the "Unlock CAAM MID" command in CSF file.
-
-The current NXP BSP implementation expects the CAAM registers to be unlocked
-when configuring CAAM to operate in non-secure TrustZone world.
-
-The Unlock command is already included by default in the signed HDMI and
-DisplayPort firmwares, on i.MX8MM devices or in case the HDMI or DisplayPort
-controllers are disabled, users must ensure this command is included in SPL CSF.
-
-- Add Unlock MID command in csf_spl.txt:
-
- [Unlock]
- Engine = CAAM
- Features = MID
-
-1.5 Signing the flash.bin binary
----------------------------------
-
-The CST tool is used for singing the flash.bin image and generating the CSF
-binary. Users should input the CSF description file created in the step above
-and receive a CSF binary, which contains the CSF commands, SRK table,
-signatures and certificates.
-
-- Create SPL CSF binary file:
-
- $ ./cst -i csf_spl.txt -o csf_spl.bin
-
-- Create FIT CSF binary file:
-
- $ ./cst -i csf_fit.txt -o csf_fit.bin
-
-1.6 Assembling the CSF in flash.bin binary
--------------------------------------------
-
-The CSF binaries generated in the step above have to be inserted into the
-flash.bin image.
-
-The CSF offsets can be obtained from the flash.bin build log:
-
-- SPL CSF offset:
-
- csf_off 0x44600
-
-- FIT CSF offset:
-
- sld_csf_off 0x58c20
-
-The signed flash.bin image can be then assembled:
-
-- Create a flash.bin copy:
-
- $ cp flash.bin signed_flash.bin
-
-- Insert csf_spl.bin in signed_flash.bin at 0x44600 offset:
-
- $ dd if=csf_spl.bin of=signed_flash.bin seek=$((0x44600)) bs=1 conv=notrunc
-
-- Insert csf_fit.bin in signed_flash.bin at 0x58c20 offset:
-
- $ dd if=csf_fit.bin of=signed_flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
-
-- Flash signed flash.bin image:
-
- $ sudo dd if=signed_flash.bin of=/dev/sd<x> bs=1K seek=33 && sync
-
-1.7 Programming SRK Hash
--------------------------
-
-As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
-fuse values are generated by the srktool and should be programmed in the
-SoC SRK_HASH[255:0] fuses.
-
-Be careful when programming these values, as this data is the basis for the
-root of trust. An error in SRK Hash results in a part that does not boot.
-
-The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
-
-- Dump SRK Hash fuses values in host machine:
-
- $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
- 0x20593752
- 0x6ACE6962
- 0x26E0D06C
- 0xFC600661
- 0x1240E88F
- 0x1209F144
- 0x831C8117
- 0x1190FD4D
-
-- Program SRK_HASH[255:0] fuses on i.MX8MQ and i.MX8MM devices:
-
- => fuse prog 6 0 0x20593752
- => fuse prog 6 1 0x6ACE6962
- => fuse prog 6 2 0x26E0D06C
- => fuse prog 6 3 0xFC600661
- => fuse prog 7 0 0x1240E88F
- => fuse prog 7 1 0x1209F144
- => fuse prog 7 2 0x831C8117
- => fuse prog 7 3 0x1190FD4D
-
-
-1.8 Verifying HAB events
--------------------------
-
-The next step is to verify that the signatures included in flash.bin image is
-successfully processed without errors. HAB generates events when processing
-the commands if it encounters issues.
-
-The hab_status U-Boot command call the hab_report_event() and hab_status()
-HAB API functions to verify the processor security configuration and status.
-This command displays any events that were generated during the process.
-
-Prior to closing the device users should ensure no HAB events were found, as
-the example below:
-
-- Verify HAB events:
-
- => hab_status
-
- Secure boot disabled
-
- HAB Configuration: 0xf0, HAB State: 0x66
-
-1.9 Closing the device
------------------------
-
-After the device successfully boots a signed image without generating any HAB
-events, it is safe to close the device. This is the last step in the HAB
-process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
-
-Once the fuse is programmed, the chip does not load an image that has not been
-signed using the correct PKI tree.
-
-- Program SEC_CONFIG[1] fuse on i.MX8MQ and i.MX8MM devices:
-
- => fuse prog 1 3 0x2000000
-
-1.10 Completely secure the device
-----------------------------------
-
-Additional fuses can be programmed for completely secure the device, more
-details about these fuses and their possible impact can be found at AN4581[1].
-
-- Program SRK_LOCK:
-
- => fuse prog 0 0 0x200
-
-- Program DIR_BT_DIS:
-
- => fuse prog 1 3 0x8000000
-
-- Program SJC_DISABLE:
-
- => fuse prog 1 3 0x200000
-
-- JTAG_SMODE:
-
- => fuse prog 1 3 0xC00000
-
-2. Authenticating additional boot images
------------------------------------------
-
-The High Assurance Boot (HAB) code located in the on-chip ROM provides an
-Application Programming Interface (API) making it possible to call back
-into the HAB code for authenticating additional boot images.
-
-The U-Boot is running in non-secure TrustZone world and to make use of this
-feature it's necessary to use a SIP call to the ATF, this is already
-implemented in hab.c code and it's transparent to the user.
-
-The process of signing an additional image is similar as in i.MX6 and i.MX7
-series devices, the steps below are using the Linux Kernel image as example.
-
-The diagram below illustrate the Image layout:
-
- ------- +-----------------------------+ <-- *load_address
- ^ | |
- | | |
- | | |
- | | |
- | | Image |
- Signed | | |
- Data | | |
- | | |
- | +-----------------------------+
- | | Padding to Image size |
- | | in header |
- | +-----------------------------+ <-- *ivt
- v | Image Vector Table |
- ------- +-----------------------------+ <-- *csf
- | |
- | Command Sequence File (CSF) |
- | |
- +-----------------------------+
- | Padding (optional) |
- +-----------------------------+
-
-2.1 Padding the image
-----------------------
-
-The Image must be padded to the size specified in the Image header, this can be
-achieved by using the od command.
-
-- Read Image size:
-
- $ od -x -j 0x10 -N 0x4 --endian=little Image
- 0000020 5000 0145
- 0000024
-
-The tool objcopy can be used for padding the image.
-
-- Pad the Image:
-
- $ objcopy -I binary -O binary --pad-to 0x1455000 --gap-fill=0x00 \
- Image Image_pad.bin
-
-2.2 Generating Image Vector Table
-----------------------------------
-
-The HAB code requires an Image Vector Table (IVT) for determining the image
-length and the CSF location. Since Image does not include an IVT this has
-to be manually created and appended to the end of the padded Image, the
-script genIVT.pl in script_examples directory can be used as reference.
-
-- Generate IVT:
-
- $ genIVT.pl
-
-Note: The load Address may change depending on the device.
-
-- Append the ivt.bin at the end of the padded Image:
-
- $ cat Image_pad.bin ivt.bin > Image_pad_ivt.bin
-
-2.3 Signing the image
-----------------------
-
-A CSF file has to be created to sign the image. HAB does not allow to change
-the SRK once the first image is authenticated, so the same SRK key used in
-the initial image must be used when extending the root of trust.
-
-CSF examples are available in ../csf_examples/additional_images/ directory.
-
-- Create CSF binary file:
-
- $ ./cst --i csf_additional_images.txt --o csf_Image.bin
-
-- Attach the CSF binary to the end of the image:
-
- $ cat Image_pad_ivt.bin csf_Image.bin > Image_signed.bin
-
-2.4 Verifying HAB events
--------------------------
-
-The U-Boot includes the hab_auth_img command which can be used for
-authenticating and troubleshooting the signed image, the Image must be
-loaded at the load address specified in the IVT.
-
-- Authenticate additional image:
-
- => hab_auth_img <Load Address> <Image Size> <IVT Offset>
-
-If no HAB events were found the Image is successfully signed.
-
-References:
-[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
- HABv4" - Rev 2.
-[2] AN12212: "Software Solutions for Migration Guide from Aarch32 to
-Aarch64" - Rev 0.
--- /dev/null
+ +=====================================================+
+ + i.MX8M family Secure Boot guide using HABv4 +
+ +=====================================================+
+
+1. HABv4 secure boot process
+-----------------------------
+
+This document describes a step-by-step procedure on how to sign and securely
+boot a bootloader image on i.MX8M family devices. It is assumed that the reader
+is familiar with basic HAB concepts and with the PKI tree generation.
+
+Details about HAB can be found in the application note AN4581[1] and in the
+introduction_habv4.txt document.
+
+1.1 Understanding the i.MX8M family flash.bin image layout
+----------------------------------------------------------
+
+Due to the new the architecture, multiple firmwares and softwares are required
+to boot i.MX8M family devices. In order to store all the images in a single
+binary the FIT (Flattened Image Tree) image structure is used.
+
+The final image is generated by the imx-mkimage project, the tool combines all
+the input images in a FIT structure, generating a flash.bin image with an
+appropriate IVT set.
+
+For a secure boot process users should ensure all images included in flash.bin
+file are covered by a digital signature.
+
+- The diagram below illustrate a signed flash.bin image layout:
+
+ +-----------------------------+
+ | |
+ | *Signed HDMI/DP FW |
+ | |
+ +-----------------------------+
+ | Padding |
+ ------- +-----------------------------+ --------
+ ^ | IVT - SPL | ^
+ Signed | +-----------------------------+ |
+ Data | | u-boot-spl.bin | |
+ | | + | | SPL
+ v | DDR FW | | Image
+ ------- +-----------------------------+ |
+ | CSF - SPL + DDR FW | v
+ +-----------------------------+ --------
+ | Padding |
+ ------- +-----------------------------+ --------
+ Signed ^ | FDT - FIT | ^
+ Data | +-----------------------------+ |
+ v | IVT - FIT | |
+ ------- +-----------------------------+ |
+ | CSF - FIT | |
+ ------- +-----------------------------+ | FIT
+ ^ | u-boot-nodtb.bin | | Image
+ | +-----------------------------+ |
+ Signed | | OP-TEE (Optional) | |
+ Data | +-----------------------------+ |
+ | | bl31.bin (ATF) | |
+ | +-----------------------------+ |
+ v | u-boot.dtb | v
+ ------- +-----------------------------+ --------
+ * Only supported on i.MX8M series
+
+The boot flow on i.MX8M devices are slightly different when compared with i.MX6
+and i.MX7 series, the diagram below illustrate the boot sequence overview:
+
+- i.MX8M boot flow:
+
+ Secure World Non-Secure World
+ |
+ |
+ +------------+ +------------+ |
+ | SPL | | i.MX 8M | |
+ | + | ---> | ROM | |
+ | DDR FW | | + HAB | |
+ +------------+ +------------+ |
+ | |
+ v |
+ +------------+ |
+ | *Signed | |
+ | HDMI/DP FW | |
+ +------------+ |
+ | |
+ v |
+ +------------+ +------------+ |
+ | FIT Image: | | SPL | |
+ | ATF + TEE | ---> | + | |
+ | + U-Boot | | DDR FW | | +-----------+
+ +------------+ +------------+ | | Linux |
+ | | +-----------+
+ v | ^
+ +------------+ | | +-------+
+ | ARM | | +-----------+ | Linux |
+ | Trusted | ----+---> | U-Boot | <--- | + |
+ | Firmware | | +-----------+ | DTB |
+ +------------+ | +-------+
+ | |
+ v |
+ +----------+ |
+ | **OP-TEE | |
+ +----------+ |
+ * Only supported on i.MX8M series
+ ** Optional
+
+Particularly on the i.MX8M, the HDMI firmware or DisplayPort firmware are the
+first image to boot on the device. These firmwares are signed and distributed by
+NXP, and are always authenticated regardless of security configuration. In case
+not required by the application the HDMI or DisplayPort controllers can be
+disabled by eFuses and the firmwares are not required anymore.
+
+The next images are not signed by NXP and users should follow the signing
+procedure as described in this document.
+
+The Second Program Loader (SPL) and DDR firmware are loaded and authenticated
+by the ROM code, these images are executed in the internal RAM and responsible
+for initializing essential features such as DDR, UART, PMIC and clock
+enablement.
+
+Once the DDR is available, the SPL code loads all the images included in the
+FIT structure to their specific execution addresses, the HAB APIs are called
+to extend the root of trust, authenticating the U-Boot, ARM trusted firmware
+(ATF) and OP-TEE (If included).
+
+The root of trust can be extended again at U-Boot level to authenticate Kernel
+and M4 images.
+
+1.2 Enabling the secure boot support in U-Boot
+-----------------------------------------------
+
+The first step is to generate an U-Boot image supporting the HAB features,
+similar to i.MX6 and i.MX7 series the U-Boot provides extra functions for
+HAB, such as the HAB status logs retrievement through the hab_status command
+and support to extend the root of trust.
+
+The support is enabled by adding the CONFIG_IMX_HAB to the build
+configuration:
+
+- Defconfig:
+
+ CONFIG_IMX_HAB=y
+
+- Kconfig:
+
+ ARM architecture -> Support i.MX HAB features
+
+1.3 Preparing the fit image
+----------------------------
+
+The imx-mkimage project is used to combines all the images in a single
+flash.bin binary, the following files are required:
+
+- U-Boot:
+ u-boot-nodtb.bin
+ u-boot-spl.bin
+ U-Boot DTB file (e.g. fsl-imx8mq-evk.dtb)
+
+- ATF image:
+ bl31.bin
+
+- DDR firmware:
+ lpddr4_pmu_train_1d_dmem.bin
+ lpddr4_pmu_train_1d_imem.bin
+ lpddr4_pmu_train_2d_dmem.bin
+ lpddr4_pmu_train_2d_imem.bin
+
+- HDMI firmware (Only in i.MX8M):
+ signed_hdmi_imx8m.bin
+
+- DisplayPort firmware (Only in i.MX8M):
+ signed_dp_imx8m.bin
+
+- OP-TEE (Optional):
+ tee.bin
+
+The procedure to build ATF and download the firmwares are out of the scope
+of this document, please refer to the Linux BSP Release Notes and AN12212[2]
+for further details.
+
+Copy all files to iMX8M directory and run the following command according to
+the target device, on this example we are building a HDMI target and also
+including the OP-TEE binary:
+
+- Assembly flash.bin binary:
+
+ $ make SOC=<SoC Name> flash_hdmi_spl_uboot
+
+The mkimage log can be used to calculate the authenticate image command
+parameters and CSF offsets:
+
+- imx-mkimage build log:
+
+ Loader IMAGE:
+ header_image_off 0x1a000
+ dcd_off 0x0
+ image_off 0x1a040
+ csf_off 0x44600
+ spl hab block: 0x7e0fd0 0x1a000 0x2e600
+
+ Second Loader IMAGE:
+ sld_header_off 0x57c00
+ sld_csf_off 0x58c20
+ sld hab block: 0x401fcdc0 0x57c00 0x1020
+
+Additional HAB information is provided by running the following command:
+
+- Printing HAB FIT information:
+
+ $ make SOC=<SoC Name> print_fit_hab
+
+ TEE_LOAD_ADDR=0xfe000000 ATF_LOAD_ADDR=0x00910000 ./print_fit_hab.sh \
+ 0x60000 fsl-imx8mq-evk.dtb
+ 0x40200000 0x5AC00 0x9AAC8
+ 0x910000 0xF56C8 0x9139
+ 0xFE000000 0xFE804 0x4D268
+ 0x4029AAC8 0x14BA6C 0x6DCF
+
+1.4 Creating the CSF description file
+--------------------------------------
+
+The CSF contains all the commands that the ROM executes during the secure
+boot. These commands instruct the HAB code on which memory areas of the image
+to authenticate, which keys to install, use and etc.
+
+CSF examples are available under doc/imx/hab/habv4/csf_examples/ directory.
+
+As explained in sections above the SPL is first authenticated by the ROM code
+and the root of trust is extended to the FIT image, hence two CSF files are
+necessary to completely sign an flash.bin image.
+
+The build log provided by imx-mkimage can be used to define the "Authenticate
+Data" parameter in CSF.
+
+- SPL "Authenticate Data" addresses in flash.bin build log:
+
+ spl hab block: 0x7e0fd0 0x1a000 0x2e600
+
+- "Authenticate Data" command in csf_spl.txt file:
+
+ Blocks = 0x7e0fd0 0x1a000 0x2e600 "flash.bin"
+
+- FIT image "Authenticate Data" addresses in flash.bin build log:
+
+ sld hab block: 0x401fcdc0 0x57c00 0x1020
+
+- FIT image "Authenticate Data" addresses in print_fit_hab build log:
+
+ 0x40200000 0x5AC00 0x9AAC8
+ 0x910000 0xF56C8 0x9139
+ 0xFE000000 0xFE804 0x4D268
+ 0x4029AAC8 0x14BA6C 0x6DCF
+
+- "Authenticate Data" command in csf_fit.txt file:
+
+ Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
+ 0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
+ 0x00910000 0x0F56C8 0x09139 "flash.bin", \
+ 0xFE000000 0x0FE804 0x4D268 "flash.bin", \
+ 0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
+
+1.4.1 Avoiding Kernel crash in closed devices
+----------------------------------------------
+
+For devices prior to HAB v4.4.0, the HAB code locks the Job Ring and DECO
+master ID registers in closed configuration. In case the user specific
+application requires any changes in CAAM MID registers it's necessary to
+add the "Unlock CAAM MID" command in CSF file.
+
+The current NXP BSP implementation expects the CAAM registers to be unlocked
+when configuring CAAM to operate in non-secure TrustZone world.
+
+The Unlock command is already included by default in the signed HDMI and
+DisplayPort firmwares. On i.MX8MM, i.MX8MN and i.MX8MP devices or in case the
+HDMI or DisplayPort controllers are disabled in i.MX8M, users must ensure this
+command is included in SPL CSF.
+
+- Add Unlock MID command in csf_spl.txt:
+
+ [Unlock]
+ Engine = CAAM
+ Features = MID
+
+1.5 Signing the flash.bin binary
+---------------------------------
+
+The CST tool is used for singing the flash.bin image and generating the CSF
+binary. Users should input the CSF description file created in the step above
+and receive a CSF binary, which contains the CSF commands, SRK table,
+signatures and certificates.
+
+- Create SPL CSF binary file:
+
+ $ ./cst -i csf_spl.txt -o csf_spl.bin
+
+- Create FIT CSF binary file:
+
+ $ ./cst -i csf_fit.txt -o csf_fit.bin
+
+1.6 Assembling the CSF in flash.bin binary
+-------------------------------------------
+
+The CSF binaries generated in the step above have to be inserted into the
+flash.bin image.
+
+The CSF offsets can be obtained from the flash.bin build log:
+
+- SPL CSF offset:
+
+ csf_off 0x44600
+
+- FIT CSF offset:
+
+ sld_csf_off 0x58c20
+
+The signed flash.bin image can be then assembled:
+
+- Create a flash.bin copy:
+
+ $ cp flash.bin signed_flash.bin
+
+- Insert csf_spl.bin in signed_flash.bin at 0x44600 offset:
+
+ $ dd if=csf_spl.bin of=signed_flash.bin seek=$((0x44600)) bs=1 conv=notrunc
+
+- Insert csf_fit.bin in signed_flash.bin at 0x58c20 offset:
+
+ $ dd if=csf_fit.bin of=signed_flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
+
+- Flash signed flash.bin image:
+
+ $ sudo dd if=signed_flash.bin of=/dev/sd<x> bs=1K seek=33 && sync
+
+1.7 Programming SRK Hash
+-------------------------
+
+As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
+fuse values are generated by the srktool and should be programmed in the
+SoC SRK_HASH[255:0] fuses.
+
+Be careful when programming these values, as this data is the basis for the
+root of trust. An error in SRK Hash results in a part that does not boot.
+
+The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
+
+- Dump SRK Hash fuses values in host machine:
+
+ $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
+ 0x20593752
+ 0x6ACE6962
+ 0x26E0D06C
+ 0xFC600661
+ 0x1240E88F
+ 0x1209F144
+ 0x831C8117
+ 0x1190FD4D
+
+- Program SRK_HASH[255:0] fuses on i.MX8M family devices:
+
+ => fuse prog 6 0 0x20593752
+ => fuse prog 6 1 0x6ACE6962
+ => fuse prog 6 2 0x26E0D06C
+ => fuse prog 6 3 0xFC600661
+ => fuse prog 7 0 0x1240E88F
+ => fuse prog 7 1 0x1209F144
+ => fuse prog 7 2 0x831C8117
+ => fuse prog 7 3 0x1190FD4D
+
+
+1.8 Verifying HAB events
+-------------------------
+
+The next step is to verify that the signatures included in flash.bin image is
+successfully processed without errors. HAB generates events when processing
+the commands if it encounters issues.
+
+The hab_status U-Boot command call the hab_report_event() and hab_status()
+HAB API functions to verify the processor security configuration and status.
+This command displays any events that were generated during the process.
+
+Prior to closing the device users should ensure no HAB events were found, as
+the example below:
+
+- Verify HAB events:
+
+ => hab_status
+
+ Secure boot disabled
+
+ HAB Configuration: 0xf0, HAB State: 0x66
+
+1.9 Closing the device
+-----------------------
+
+After the device successfully boots a signed image without generating any HAB
+events, it is safe to close the device. This is the last step in the HAB
+process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
+
+Once the fuse is programmed, the chip does not load an image that has not been
+signed using the correct PKI tree.
+
+- Program SEC_CONFIG[1] fuse on i.MX8M family devices:
+
+ => fuse prog 1 3 0x2000000
+
+1.10 Completely secure the device
+----------------------------------
+
+Additional fuses can be programmed for completely secure the device, more
+details about these fuses and their possible impact can be found at AN4581[1].
+
+- Program SRK_LOCK:
+
+ => fuse prog 0 0 0x200
+
+- Program DIR_BT_DIS:
+
+ => fuse prog 1 3 0x8000000
+
+- Program SJC_DISABLE:
+
+ => fuse prog 1 3 0x200000
+
+- JTAG_SMODE:
+
+ => fuse prog 1 3 0xC00000
+
+2. Authenticating additional boot images
+-----------------------------------------
+
+The High Assurance Boot (HAB) code located in the on-chip ROM provides an
+Application Programming Interface (API) making it possible to call back
+into the HAB code for authenticating additional boot images.
+
+The U-Boot is running in non-secure TrustZone world and to make use of this
+feature it's necessary to use a SIP call to the ATF, this is already
+implemented in hab.c code and it's transparent to the user.
+
+The process of signing an additional image is similar as in i.MX6 and i.MX7
+series devices, the steps below are using the Linux Kernel image as example.
+
+The diagram below illustrate the Image layout:
+
+ ------- +-----------------------------+ <-- *load_address
+ ^ | |
+ | | |
+ | | |
+ | | |
+ | | Image |
+ Signed | | |
+ Data | | |
+ | | |
+ | +-----------------------------+
+ | | Padding to Image size |
+ | | in header |
+ | +-----------------------------+ <-- *ivt
+ v | Image Vector Table |
+ ------- +-----------------------------+ <-- *csf
+ | |
+ | Command Sequence File (CSF) |
+ | |
+ +-----------------------------+
+ | Padding (optional) |
+ +-----------------------------+
+
+2.1 Padding the image
+----------------------
+
+The Image must be padded to the size specified in the Image header, this can be
+achieved by using the od command.
+
+- Read Image size:
+
+ $ od -x -j 0x10 -N 0x4 --endian=little Image
+ 0000020 5000 0145
+ 0000024
+
+The tool objcopy can be used for padding the image.
+
+- Pad the Image:
+
+ $ objcopy -I binary -O binary --pad-to 0x1455000 --gap-fill=0x00 \
+ Image Image_pad.bin
+
+2.2 Generating Image Vector Table
+----------------------------------
+
+The HAB code requires an Image Vector Table (IVT) for determining the image
+length and the CSF location. Since Image does not include an IVT this has
+to be manually created and appended to the end of the padded Image, the
+script genIVT.pl in script_examples directory can be used as reference.
+
+- Generate IVT:
+
+ $ genIVT.pl
+
+Note: The load Address may change depending on the device.
+
+- Append the ivt.bin at the end of the padded Image:
+
+ $ cat Image_pad.bin ivt.bin > Image_pad_ivt.bin
+
+2.3 Signing the image
+----------------------
+
+A CSF file has to be created to sign the image. HAB does not allow to change
+the SRK once the first image is authenticated, so the same SRK key used in
+the initial image must be used when extending the root of trust.
+
+CSF examples are available in ../csf_examples/additional_images/ directory.
+
+- Create CSF binary file:
+
+ $ ./cst --i csf_additional_images.txt --o csf_Image.bin
+
+- Attach the CSF binary to the end of the image:
+
+ $ cat Image_pad_ivt.bin csf_Image.bin > Image_signed.bin
+
+2.4 Verifying HAB events
+-------------------------
+
+The U-Boot includes the hab_auth_img command which can be used for
+authenticating and troubleshooting the signed image, the Image must be
+loaded at the load address specified in the IVT.
+
+- Authenticate additional image:
+
+ => hab_auth_img <Load Address> <Image Size> <IVT Offset>
+
+If no HAB events were found the Image is successfully signed.
+
+References:
+[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
+ HABv4" - Rev 2.
+[2] AN12212: "Software Solutions for Migration Guide from Aarch32 to
+Aarch64" - Rev 0.
operations.
This feature is supported in i.MX 50, i.MX 53, i.MX 6, i.MX 7 series and
- i.MX 8M, i.MX 8MM devices.
+i.MX 8M family (i.MX 8M, i.MX 8MM, i.MX 8MN, i.MX 8MP devices).
Step-by-step guides are available under doc/imx/habv4/guides/ directory,
users familiar with HAB and CST PKI tree generation should refer to these
projects / u-boot.git / commitdiff