RT1015 APP BEE encryption operation method
1 Introduction
NXP RT product BEE encryption can use the master key(the fixed OTPMK SNVS key) or the User Key method. The Master key method is the fixed key, and the user can’t modify it, in the practical usage, a lot of customers need to define their own key, in this situation, customer can use the use key method. This document will take the NXP RT1015 as an example, use the flexible user key method to realize the BEE encryption without the HAB certification.
The BEE encryption test will on the MIMXRT1015-EVK board, mainly three ways to realize it: MCUBootUtility tool , the Commander line method with MFGTool and the MCUXPresso Secure Provisioning tool to download the BEE encryption code.
2 Preparation
2.1 Tool preparation
MCUBootUtility download link：
https://github.com/JayHeng/NXP-MCUBootUtility/archive/v2.3.0.zip
image_enc2.zip download link：
https://www.cnblogs.com/henjay724/p/10189602.html
After unzip the image_enc2.zip, will get the image_enc.exe, put it under the MCUBootUtility tool folder: NXP-MCUBootUtility-2.3.0\tools\image_enc2\win
RT1015 SDK download link：
2.2 app file preparation
This document will use the iled_blinky MCUXpresso IDE project in the SDK_2.8.0_EVK-MIMXRT1015 as an example, to generate the app without the XIP boot header. Generate evkmimxrt1015_igpio_led_output.s19 will be used later.
Fig 1
3 MCUbootUtility BEE encryption with user key
This chapter will use MCUBootUtility tool to realize the app BEE encryption with the user key, no HAB certification.
3.1 MIMXRT1015-EVK original fuse map
Before doing the BEE encryption, readout the original fuse map, it will be used to compare with the fuse map after the BEE encryption operation. Use the MCUbootUtility tool effuse operation utility page can read out all the fuse map.
Fig 2
3.2 MCUbootutility BEE encryption configuration
Fig 3
This document just use the BEE encryption, without the HAB certificate, so in the “Enable Certificate for HAB(BEE/OTFAD) encryption”, select: No.
Check Fig4, Select the”Key storage region” as flexible user keys, the protect region 0 start from 0X60001000, length is 0x2000, didn’t encrypt all the app region, just used to compare the original app with the BEE encrypted app code, we can find from 0X60003000, the code will be the plaintext code. But from 0X60001000 to 0X60002FFF will be the BEE encrypted code.
After the configuration, Click the button”all in one action”, burn the code to the external QSPI flash.
Fig 4
Fig 5
SW_GP2 region in the fuse can be burned separated, click the button”burn DEK data” is OK.
Fig 6
Then read out all the fuse map again, we can find in the cfg1, BEE_KEY0_SEL is SW-GP2, it defines the BEE key is using the flexible use key method, not the fixed master key.
Fig 7
Then, readout the BEE burned code from the flash with the normal burned code from the flash, and compare with it, the detail situation is:
Fig 8
Fig 9
Fig 10
Fig 11
Fig 12
We can find, after the BEE encryption, 0X60001000 to 0X60002FFF is the encrypted code, 0X6000400 area add the EKIB0 data, 0X6000480 area add the EPRDB0 data. Because we just select the BEE engine 0, no BEE engine 1, then we can find 0X60000800 EKIB1 and EPRDB1 are all 0, not the valid data.
From 0X60003000, we can find the app data is the plaintext data, the same result with our expected BEE configuration app encrypted range.
Until now, we already realize the MCUBootUtility tool BEE encryption. Exit the serial download mode, configure the MIMXRT10150-EVK on board SW8 as: 1-ON, 2-OFF, 3-ON, 4-OFF, reset the board, we can find the on board user LED is blinking, the BEE encrypted code is working.
4 BEE encryption with the Commander line mode
In practical usage, a lot of customers also need to use the commander line mode to realize the BEE encryption operation, and choose MFGTool download method. So this document will also give the way how to use the SDK SDK_2.8.0_EVK-MIMXRT1015\middleware\mcu-boot\bin\Tools and image_enc tool to realize the BEE commander line method encryption operation, then use the MFGTool download the BEE encrypted code to the RT1015 external QSPI flash.
Because from SDK2.8.0, blhost, elftosb related tools will not be packed in the SDK middleware directly, the customer need to download it from this link:
4.1 Commander line file preparation
Prepare one folder, put elftosb.exe, image_enc.exe，app file evkmimxrt1015_iled_blinky_0x60002000.s19，RemoveBinaryBytes.exe to that folder. RemoveBinaryBytes.exe is used to modify the bin file, it can be downloaded from this link:
https://community.nxp.com/pwmxy87654/attachments/pwmxy87654/imxrt/8733/2/Test.zip
(https://community.nxp.com/t5/i-MX-RT/RT1015-BEE-XIP-Step-Confirm/m-p/1070076/page/2)
Then prepare the following files:
imx-flexspinor-normal-unsigned.bd
imxrt1015_app_flash_sb_gen.bd
burn_fuse.bd
4.1.1 imx-flexspinor-normal-unsigned.bd
imx-flexspinor-normal-unsigned.bd files is used to generate the app file evkmimxrt1015_iled_blinky_0x60002000.s19 related boot .bin file, which is include the IVT header code:
ivt_evkmimxrt1015_iled_blinky_0x60002000.bin
ivt_evkmimxrt1015_iled_blinky_0x60002000_nopadding.bin
bd file content is
/*********************file start****************************/
options {
flags = 0x00;
startAddress = 0x60000000;
ivtOffset = 0x1000;
initialLoadSize = 0x2000;
//DCDFilePath = "dcd.bin";
# Note: This is required if the default entrypoint is not the Reset_Handler
# Please set the entryPointAddress to Reset_Handler address
// entryPointAddress = 0x60002000;
}
sources {
elfFile = extern(0);
}
section (0)
{
}
/*********************file end****************************/
4.1.2 imxrt1015_app_flash_sb_gen.bd
This file is used to configure the external QSPI flash, and realize the program function, normally use this .bd file to generate the .sb file, then use the MFGtool select this .sb file and download the code to the external flash.
/*********************file start****************************/
sources {
myBinFile = extern (0);
}
section (0) {
load 0xc0000007 > 0x20202000;
load 0x0 > 0x20202004;
enable flexspinor 0x20202000;
erase 0x60000000..0x60005000;
load 0xf000000f > 0x20203000;
enable flexspinor 0x20203000;
load myBinFile > 0x60000400;
}
/*********************file end****************************/
4.1.3 burn_fuse.bd
BEE encryption operation need to burn the fuse map, but the fuse data is the one time operation from 0 to 1, here will separate the burn fuse operation, only do the burn fuse operation during the first time which the RT chip still didn’t be modified the fuse map. Otherwise, in the next operation, just modify the app code, don’t need to burn the fuse. Burn_fuse.bd is mainly used to configure the fuse data which need to burn the related fuse map, then generate the .sb file, and use the MFGTool burn it with the app together.
/*********************file start****************************/
# The source block assign file name to identifiers
sources {
}
constants {
}
# !!!!!!!!!!!! WARNING !!!!!!!!!!!!
# The section block specifies the sequence of boot commands to be written to the SB file
# Note: this is just a template, please update it to actual values in users' project
section (0) {
# program SW_GP2
load fuse 0x76543210 > 0x29;
load fuse 0xfedcba98 > 0x2a;
load fuse 0x89abcdef > 0x2b;
load fuse 0x01234567 > 0x2c;
# Program BEE_KEY0_SEL
load fuse 0x00003000 > 0x6;
}
/*********************file end****************************/4.2 BEE commander line operation steps
Create the rt1015_bee_userkey_gp2.bat file, the content is:
elftosb.exe -f imx -V -c imx-flexspinor-normal-unsigned.bd -o ivt_evkmimxrt1015_iled_blinky_0x60002000.bin evkmimxrt1015_iled_blinky_0x60002000.s19
image_enc.exe hw_eng=bee ifile=ivt_evkmimxrt1015_iled_blinky_0x60002000.bin ofile=evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted.bin base_addr=0x60000000 region0_key=0123456789abcdeffedcba9876543210 region0_arg=1,[0x60001000,0x2000,0] region0_lock=0 use_zero_key=1 is_boot_image=1
RemoveBinaryBytes.exe evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted.bin evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin 1024
elftosb.exe -f kinetis -V -c program_imxrt1015_qspi_encrypt_sw_gp2.bd -o boot_image_encrypt.sb evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin
elftosb.exe -f kinetis -V -c burn_fuse.bd -o burn_fuse.sb
pause
Fig 13
Fig 14
it mainly has 5 steps:
4.2.1 elftosb generate app file with IVT header
elftosb.exe -f imx -V -c imx-flexspinor-normal-unsigned.bd -o ivt_evkmimxrt1015_iled_blinky_0x60002000.bin evkmimxrt1015_iled_blinky_0x60002000.s19
After this commander, will generate two files with the IVT header:
ivt_evkmimxrt1015_iled_blinky_0x60002000.bin，ivt_evkmimxrt1015_iled_blinky_0x60002000_nopadding.bin
Here, we will use the ivt_evkmimxrt1015_iled_blinky_0x60002000.bin
4.2.2 image_enc generate the app related BEE encrypted code
image_enc.exe hw_eng=bee ifile=ivt_evkmimxrt1015_iled_blinky_0x60002000.bin ofile=evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted.bin base_addr=0x60000000 region0_key=0123456789abcdeffedcba9876543210 region0_arg=1,[0x60001000,0x2000,0] region0_lock=0 use_zero_key=1 is_boot_image=1
About the keyword meaning in the image_enc, we can run the image_enc directly to find it.
Fig 15
This commander line run result will be the same as the MCUBootUtility configuration. The encryption area from 0X60001000, the length is 0x2000, more details, can refer to Fig 4.
After the operation, we can get this file:
evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted.bin
4.2.3 RemoveBinaryBytes remove the BEE encrypted file above 1024 bytes
RemoveBinaryBytes.exe evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted.bin evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin 1024
This commaner will used to remove the BEE encrypted file, the above 0X400 length data, after the modification, the encrypted file will start from EKIB0 directly.
After running it, will get this file：
evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin
4.2.4 elftosb generate BEE encrypted app related sb file
elftosb.exe -f kinetis -V -c program_imxrt1015_qspi_encrypt_sw_gp2.bd -o boot_image_encrypt.sb evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin
This commander will use evkmimxrt1015_iled_blinky_0x60002000_bee_encrypted_remove1K.bin and program_imxrt1015_qspi_encrypt_sw_gp2.bd to generate the sb file which can use the MFGTool download the code to the external flash
After running it, we can get this file:
boot_image_encrypt.sb
4.2.5 elftosb generate the burn fuse related sb file
elftosb.exe -f kinetis -V -c burn_fuse.bd -o burn_fuse.sb
This commander is used to generate the BEE code related fuse bits sb file, this sb file will be burned together with the boot_image_encrypt.sb in the MFGTool. But after the fuse is burned, the next app modify operation don’t need to add the burn fuse operation, can download the add directly.
After running it, can get this file:
burn_fuse.sb
4.3 MFGTool downloading
MIMXRT1015-EVK board enter the serial downloader mode, find two USB cable, plug it in J41 and J9 to the PC. MFGTool can be found in folder:
SDK_2.8.0_EVK-MIMXRT1015\middleware\mcu-boot\bin\Tools\mfgtools-rel
If need to burn the burn_fuse.sb, need to modify the ucl2.xml, folder path:
\SDK_2.8.0_EVK-MIMXRT1015\middleware\mcu-boot\bin\Tools\mfgtools-rel\Profiles\MXRT1015\OS Firmware
Add the following list to realize it.
<LIST name="MXRT1015-beefuse_DevBoot" desc="Boot Flashloader">
<!-- Stage 1, load and execute Flashloader -->
<CMD state="BootStrap" type="boot" body="BootStrap" file="ivt_flashloader.bin" > Loading Flashloader. </CMD>
<CMD state="BootStrap" type="jump" onError = "ignore"> Jumping to Flashloader. </CMD>
<!-- Stage 2, burn BEE related fuse using Flashloader -->
<CMD state="Blhost" type="blhost" body="get-property 1" > Get Property 1. </CMD> <!--Used to test if flashloader runs successfully-->
<CMD state="Blhost" type="blhost" body="receive-sb-file \"Profiles\\MXRT1015\\OS Firmware\\burn_fuse.sb\"" > Program Boot Image. </CMD>
<CMD state="Blhost" type="blhost" body="reset" > Reset. </CMD> <!--Reset device-->
<!-- Stage 3, Program boot image into external memory using Flashloader -->
<CMD state="Blhost" type="blhost" body="get-property 1" > Get Property 1. </CMD> <!--Used to test if flashloader runs successfully-->
<CMD state="Blhost" type="blhost" timeout="15000" body="receive-sb-file \"Profiles\\MXRT1015\\OS Firmware\\ boot_image_encrypt.sb\"" > Program Boot Image. </CMD>
<CMD state="Blhost" type="blhost" body="Update Completed!">Done</CMD>
</list>
If already have burned the Fuse bits, just need to update the app, then we can use MIMXRT1015-DevBoot
<LIST name="MXRT1015-DevBoot" desc="Boot Flashloader">
<!-- Stage 1, load and execute Flashloader -->
<CMD state="BootStrap" type="boot" body="BootStrap" file="ivt_flashloader.bin" > Loading Flashloader. </CMD>
<CMD state="BootStrap" type="jump" onError = "ignore"> Jumping to Flashloader. </CMD>
<!-- Stage 2, Program boot image into external memory using Flashloader -->
<CMD state="Blhost" type="blhost" body="get-property 1" > Get Property 1. </CMD> <!--Used to test if flashloader runs successfully-->
<CMD state="Blhost" type="blhost" timeout="15000" body="receive-sb-file \"Profiles\\MXRT1015\\OS Firmware\\boot_image.sb\"" > Program Boot Image. </CMD>
<CMD state="Blhost" type="blhost" body="Update Completed!">Done</CMD>
</list>Which detail list is select, it is determined by the cfg.ini name item
[profiles]
chip = MXRT1015
[platform]
board =
[LIST]
name = MXRT1015-DevBoot
Because my side do the MCUbootUtility operation at first, then the fuse is burned, so in the commander line, I just use MXRT1015-DevBoot download the app.sb
Fig 16
We can find, it is burned successfully, click stop button, Configure the MIMXRT1015-EVK on board SW8 as 1-ON,2-OFF,3-ON,4-OFF, reset the board, we can find the on board LED is blinking, it means the commander line also can finish the BEE encryption successfully.
5 MCUXpresso Secure Provisioning BEE unsigned operation
This part will use the MCUXPresso Secure Provisioning tool to finish the BEE unsigned image downloading BEE unsigned image is just use the BEE, no certification.
5.1 Tool downloading
MCUXPresso Secure Provisioning download link is:
Download it and install it, it’s better to read the tool document at first:
C:\nxp\MCUX_Provi_v2.1\MCUXpresso Secure Provisioning Tool.pdf
5.2 Operation Steps
Step1: Create the new tool workspace
File->New Workspace, select the workspace path.
Fig 17
Step2: Chip boot related configuration
Fig 18
Here, please note, the boot type need to select as XIP Encrypted(BEE User Keys) unsigned, which is not added the HAB certification function.
Step3: USB connection
Connect Select USB, it will use the USB HID to connect the board in serial download mode, so the MIMXRT1015-EVK board need insert the USB port to the J9, and the board need to enter the serial download mode:
SW8:1-ON,2-OFF,3-OFF,4-ON
Connect Test Connection Button, the connection result is:
Fig 19
We can see the connection is OK, due to this board has done the BEE operation in the previous time, so the related BEE fuse is burned, then we can find the BEE key and the key source SW-GP2 fuse already has data.
Step4: image selection
Just like the previous content, prepare one app image.
Step 5: XIP Encryption(BEE user keys) configuration
Fig 20
Here, it will need to select which engine, we select Engine0, BEE engine KEY use zero key, key source use the SW-GP2, then the detail user key data: 0123456789abcdeffedcba9876543210
Will be wrote to the swGp2 fuse area.
Because my board already do that fuse operation, so here it won’t burn the fuse again.
Step 6: build image
Fig 21
Here, we will find, after this operation, the tool will generate 5 files:
1) evkmimxrt1015_iled_blinky_0x60002000.bin
2) evkmimxrt1015_iled_blinky_0x60002000_bootable.bin
3) evkmimxrt1015_iled_blinky_0x60002000_bootable_nopadding.bin
4) evkmimxrt1015_iled_blinky_0x60002000_nopadding.bin
5) evkmimxrt1015_iled_blinky_0x60002000_nopadding_ehdr0.bin
1), 2), 3) is the plaintext file, 1) and 2) are totally the same, this file maps the data from base 0, from 0x1000 it is IVT+BD+DCD, from 0X2000 is app, so these files are the whole image, just except the FlexSPI Configuration block data, which should put from base address 0. 3) it is the 2) image just delete the first 0X1000 data, and just from IVT+BD+DCD+app.
4) ,5) is the BEE encrypted image, 4) is related to 3), just the BEE encrypted image, 5) is the EKIB0, EPRDB0 data, which should be put in the real address from 0X60000400, it is the BEE Encrypted Key Info Block 0 and Encrypted Protection Region Descriptor Block 0 data, as we just use the engine0, so just have the engin0 data.
In fact, the BEE whole image contains : FlexSPI Configuration block data +IVT+BD+DCD+APP
FlexSPI Configuration block data is the plaintext, but from 0X60001000 to 0X60002fff is the encrypted image.
Step 7: burn the encrypted image
Fig 22
Click the Write Image button, to finish the BEE image program.
Here, just open the bee_user_key0.bin, we will find, it is just the user key data which is defined in Fig 20, which also should be written to the swGp2 fuse.
Check the log, we will find it mainly these process:
Erase image from 0x60000000, length is 0x5000.
Generate the flexSPI Configuration block data, and download from 0x60000000
Burn evkmimxrt1015_iled_blinky_0x60002000_nopadding_ehdr0.bin to 0X60000400
Burn evkmimxrt1015_iled_blinky_0x60002000_nopadding.bin to 0x60001000
Modify the MIMXRT1015-EVK SW8:1-ON,2-OFF,3-ON,4-OFF, reset or repower on the board, we will find the on board led is blinking, it means the bee encrypted image already runs OK.
Please note: SW8_1 is the Encrypted XIP pin, it must be enable, otherwise, even the BEE encrypted image is downloaded to the external flash, but the boot will be failed, as the ROM will use normal boot not the BEE encrypted boot. So, SW8_1 should be ON.
Following pictures are the BEE encrypted image readout file to compare with the tool generated files.
Fig 23
Fig 24
Fig 25
Fig 26
Fig 27
About the MCUBootUtility lack the BEE tool image_enc.exe, we also can use the MCUXPresso Secure Provisioning’s image_enc.exe:
Copy:
C:\nxp\MCUX_Provi_v2.1\bin\tools\image_enc\win\ image_enc.exe
To the MCUbootUtility folder:
NXP-MCUBootUtility-3.2.0\tools\image_enc2\win
Attachment also contains the video about this tool usage operation.
