Security Boot User Guide¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	07/20/2023
1.1	Added anti rollback function Updated automatic signature function	01/04/2024
1.2	Reorganize the document structure	01/31/2024
1.3	securityboot new bootflow	02/02/2024

1. Overview¶

In order to prevent the firmware of user products from being copied or flashed, the Sigmastar firmware automatically performs signature verification (or signature verification + decryption) during the startup process. Signature verification is to prevent the image content loaded by the software from being maliciously tampered with. Encryption and decryption are optional. Generally, image encryption is to prevent the information in the image from being leaked, while image verification is to prevent the image information from being tampered with. Users can choose according to their own needs. There are two core steps in using Security Boot: artificially signing (or encrypting + signing) the image file, and burning the corresponding key used for the signature in the chip OTP.

Figure 1: Overall process of signature verification and decryption

For a detailed overview of the system startup process illustrated, please refer to Security boot system flowchapter for details)

The common way to burn chip OTP is to use otpctrl cmd under uboot (See OTP Usage Reference chapter for details). Please note that OTP burning cannot be reversed. In order to prevent misoperation from causing the system to fail to start or even the IC to become invalid, it is generally recommended that developers first use the debugging process to confirm that the key content is correct. The common way to sign an image is to use security_boot_tools to automatically process the alkaid image package (see 5. Security_boot_tools Tool Usage chapter for details). If the customer has special needs, you can also choose the manual signing method "Manual Signature User Guide".

Security Boot also provides an Anti-rollback mechanism to ensure that the image version that can be loaded and started normally must be higher than the version number stored by the user in the OTP (For details, see 3. Anti-rollback Principle), users can use it according to their own needs. There are two core steps to turning on Anti-rollback: using the security_boot_tools signing process to embed the version number in the image, and saving the intercepted image version number in the chip OTP.

The Sigmastar chip also provides hardware design to prevent error injection and signal analysis (Multiple Round, SCA, key2sha1) to prevent new cryptanalysis methods from interfering with or analyzing the chip encryption and decryption process, effectively increasing the difficulty of system cracking (For details, see 4. The principles of preventing error injection and signal analysis), users can use it according to their own needs. Enabling (Multiple Round, SCA, key2sha1) functions has nothing to do with the image itself. The core work is only one step: burning OTP to enable specified functions.

2. Security Boot Principles¶

2.1. Enable Security Boot¶

After burning the OTP Key, to actually start Security Boot, you need to burn the corresponding fields of OTP_Secure_Boot in the OTP (For details on the OTP burning method, see OTP Usage Reference, burn this field to 0xFFFFFFFF, the Security Boot of OTP will be activated. (Note: It cannot be turned off after it is enabled, and the Security Boot flow will be forced every time it is started).

2.2. Single Image Signature and Security Boot Process¶

Generate Signature is generally completed by executing the security_boot_tools script on the local side. The process is as follows:

security_boot_tools calculates SHA-256 on the Image file and generates Digest
Perform encryption through RSA-2048 to generate a 256Bytes signature.
Embed signature at the end of Image
Burn the Image and start it in the system memory.

Verify Signature is executed in the firmware boot flow. The process is as follows:

The boot code at each stage will perform SHA-256 calculation on the next image and generate Digest
Take out the signature embedded in the tail according to the header information to decrypt RSA-2048 to generate Digest'
Compare Digest and Digest'. If the comparison is consistent, Verify succeeds, otherwise Verify fails.

Figure 2: Signing Security Boot process

2.3. Single Image Signature + Encryption and Security Boot Process¶

Generate Signature is generally completed by executing the security_boot_tools script on the local side: security_boot_tools first encrypts the Image into a Cipher file through AES, then performs SHA-256 calculation on the Cipher file to generate a Digest, and then performs encryption actions through RSA-2048 to generate a 256Bytes signature. Then embed the signature into the Image backend, and finally burn the Image and start it in the system memory.

Verify Signature is in the boot flow. The boot code at each stage performs SHA-256 calculation on the next image, generates Digest, and extracts and embeds it based on the header information. After extracting the Signature for RSA-2048 decryption, Digest' is generated. Finally compare Digest and Digest'. If the comparison is successful, AES decryption is performed on the Cipher file, and finally it is decrypted into an image that can be booted.

Figure 3: Signature + Encryption Security Boot Process

Notes:

IPL only supports AES-CBC encryption, while IPL_CUST does not support encryption. Other images support AES (ECB/CBC/CTR encryption). When using CBC/CTR mode, the corresponding IV key will be made into a 32-byte append paragraph by security_boot_tools and embedded in the image information (For details, see 3.1. Append data chapter).

2.4. Image File Change in Security Boot Flow¶

Figure 3.1: Image File Change

Note:

IPL/IPL_CUST does not have a uimage header, but has its own special header that does not participate in encryption. The specific changes to this header are introduced in section 2.5.1.
Except for IPL/IPL_CUST/Rootfs, a separate layer of secure_boot header will be added to the header of other images to indicate that the image already supports secure boot and this header does not participate in encryption and signature.

2.5. Key Introduction¶

From the perspective of key usage, the same image signature and verification must use a pair of RSA Private Key and RSA Public Key, and the same AES Key is used for encryption and decryption.

2.5.1. RSA Public Key¶

Up to 3 groups of RSA Public Key are used in the signature verification process.

The first one is OTP Key. This Key will be automatically loaded from the OTP by the Hardware after the system is powered on. It is used to verify the reliability of the IPL. Software cannot intervene in the loading and verification process. The content of the OTP Key can be burned to the designated address of the OTP through U-Boot's Command Line. Once the OTP KEY is locked and read, the CPU or other debugging tools can no longer access rsakey (the same is true for the OTP aes key). At this time, only the aesdma engine can access.

The second key is CUST Key. This Key will be embedded in the bin file of IPL and used to verify the reliability of IPL_CUST in the entire boot flow through Software. Because the reliability of IPL is guaranteed, therefore the verification of IPL_CUST/TF -A/OPTEE process is also reliable. As for the content of CUST KEY, you usually use the security_boot_tools tool to insert the key file into the specified location of the bin file content of the IPL.

Figure 4: IPL Structure

The third key is Image Key. This Key will be embedded in the bin file of IPL_CUST and used by Software to verify the reliability of UBOOT/VMM/RTOS/LINUX/ROOTFS in the entire boot flow, because the reliability of IPL_CUST has guaranteed, so the process of verifying all subsequent images is also reliable. As for the content of the Image Key, the security_boot_tools tool is generally used to insert the key file into the specified location of the bin file content of IPL_CUST.

Figure 5: IPL_CUST Structure

2.5.2. AES KEY¶

Up to 8 AES Key are used in the decryption process.

During the bootflow process of the Sigmastar firmware, the Hardware loads the AES key specified in the OTP to the crypto engine for image decryption. As for which of the eight AES keys to use for the image, you generally use the security_boot_tools tool to embed the specified AES key information in the image (See 3.1. Append Data for details). Except that IPL only supports CBC mode and IPL_CUST does not support encryption, other images support ECB/CBC/CTR mode. Generally, the security_boot_tools tool is used to embed IV information in the image.

All AES Keys used for decryption by the bootload image need to be burned into the OTP storage unit. The OTP storage unit can store up to 8 128-bit AESKEYs or 4 256-bit AESKEYs. All bootload images can arbitrarily specify any one of the eight keys, and even all bootload images share one of the keys.

2.6. Security boot system flow介绍¶

The following figure shows the Security Boot Flow structure from ROM to Linux Kernel, where Signature is the signature data part. The Signature of each Flow will be embedded at the end of the corresponding bin file. Each Flow includes the actions of Get Key and Authenticate until Linux Kernel and some flows support decryption (whether to enable decryption depends on the requirements).

Figure 6: Boot Flow Structure

Authenticate IPL by OTP Key-RSA

This process is for the ROM code to read the RSA Public Key from the OTP and then verify the signature of the IPL. Since the RSA Public Key of OTP can perform Write Lock action (which will be mentioned in detail in the following chapters) to prevent it from being written or read again, the RSA Public Key of OTP can not be replaced, thus ensuring that the IPL will not be tampered with. If the encryption mechanism is enabled, the ROM code continues to read the AES key from the OTP to decrypt the IPL based on OTP_ROM_SEL_AESKEY.
Authenticate TF-A by IPL's CUST Key-RSA

This process is for IPL to read the CUST RSA Public Key embedded in IPL in advance and then verify the signature of TF-A. If the encryption mechanism is enabled, IPL continues to read the AES key from the OTP to decrypt TF-A based on the IV and aes_keynum information in the append data in the TF-A image.
Authenticate OP-TEE by IPL's CUST Key-RSA

This process is for IPL to read the CUST RSA Public Key embedded in IPL in advance and then verify the signature of OP-TEE. If the encryption mechanism is enabled, IPL continues to read the AES key from the OTP to decrypt the OP-TEE based on the IV and aes_keynum information in the append data in the OP-TEE image.
Authenticate IPL_CUST by IPL's CUST Key-RSA

This process is for IPL to read the CUST RSA Public Key embedded in IPL in advance and then verify the signature of IPL_CUST. Since IPL cannot be tampered with, it is guaranteed that the CUST RSA Public Key embedded in IPL will not be tampered with, thus ensuring that IPL_CUST will not be tampered with. IPL_CUST does not support encryption.
Authenticate U-Boot by IPL_CUST's Image Key-RSA

This process is for IPL_CUST to read the Image RSA Public Key embedded in IPL_CUST in advance and then verify the signature of U-Boot. If the encryption mechanism is enabled, IPL_CUST continues to read the AES key from the OTP to decrypt U-Boot based on the IV and aes_keynum information in the append data in the U-Boot image.
Authenticate Kernel/ramdiskfs by IPL_CUST's Image Key-RSA

This process is for U-Boot bootcmd to read the Image RSA Public Key embedded in IPL_CUST in advance and then verify the signature of kernel/ramdiskfs. If the encryption mechanism is enabled, bootcmd continues to read the AES key from the OTP to decrypt the kernel/ramdiskfs based on the IV and aes_keynum information in the append data in the kernel/ramdiskfs image .

3. Anti-rollback Principle¶

The anti-rollback mechanism is designed to prevent IPL/IPL_CUST/TF-A/OPTEE/UBOOT/KERNEL from being downgraded to previous versions. The boot code at each stage is compared with the corresponding OTP Version saved in the OTP by checking the Image Version in the image information of the next stage boot code (IPL/IPL_CUST/TF-A/OPTEE/UBOOT/KERNEL). If:

Image Version >= OTP Version ==> Load and start the next stage of boot code image normally

Image Version < OTP Version ==> Prompts that the system is stuck and does not start the next stage of boot code image

This is to ensure that the version of IPL/IPL_CUST/TF-A/OPTEE/UBOOT/KERNEL is the latest.

The following is the number of available jump versions for each Image (For details on otp version burning, please see OTP Usage Reference.

Name	Maximum number of editions	otp name	otp cmd offset range
IPL	64	OTP_VERSION_CTL	0x0 ~ 0x100
IPL_CUST	16	OTP_VERSION2_CTL	0x0 ~ 0x40
tfa	24	OTP_VERSION2_CTL	0x40 ~ 0xA0
optee	24	OTP_VERSION2_CTL	0xA0 ~ 0x100
uboot	24	OTP_VERSION2_CTL	0x100 ~ 0x160
kernel	24	OTP_VERSION2_CTL	0x160 ~ 0x1C0

Notes:

In OTP Version, 4 bytes are used to represent the upgraded version. Taking IPL as an example, when the IPL OTP Version is upgraded from 0 to 1, you need to use the OTP_VERSION_CTL command to burn 0x0-0x4 into 0xFFFF FFFF; when the IPL OTP Version needs to be upgraded to 2 again, you need to use the OTP_VERSION_CTL command to burn 0x4-0x8 into 0xFFFFFFFF;
Image Version is the version number of the current image. For IPL and IPL_CUST, the Image Version is stored in the header data; for TF-A/OPTEE/UBOOT/KERNEL, the Image Version is stored in the appended data; other than that Although image (VMM/RTOS/PM_RTOS/ROOTFS) will also append appended data, it does not support the anti-rollback function.
otp version can have automatic update function (off by default). When the header version is greater than the otp version, the otp version will be updated to be consistent with the header version.

3.1. Append Data¶

As long as the securityboot function is used , except for IPL/IPL_CUST, security_boot_tools will process every other Image (UBOOT/TF-A/VMM/KERNEL/OPTEE/RTOS, etc.) in the same way: first append 32byte appended data to the end, and then append 256 /512 byte signature data.

Figure 7: Appended Data Structure

The following is the description of 32byte appended data:

Member	Description
magic	Retrieval flag, fixed to "SSTARSBT"
pend_version	Software version of Secure append
sstar_pend_size	The length of Secure append, fixed at 32Byte
aes_msg	bit 0 - decrypt_enable. bit [1:2] - 00:ecb; 01: ctr; 10:cbc
AntiRollback_version	Version number for image other than IPL and IPL_CUST
IV1&IV2	The IV value required for CBC/CTR decryption
aes_keynum	0000 ==> Not encrypted by AES 0100 ==> AES256 with {Key1[127:0], Key2[127:0] 0101 ==> AES256 with {Key3[127:0], Key4[127:0] 0110 ==> AES256 with {Key5[127:0], Key6[127:0] 0111 ==> AES256 with {Key7[127:0], Key8[127:0] 1000 ==> AES128 with Key1[127:0] 1001 ==> AES128 with Key2[127:0] 1010 ==> AES128 with Key3[127:0] 1011 ==> AES128 with Key4[127:0] 1100 ==> AES128 with Key5[127:0] 1101 ==> AES128 with Key6[127:0] 1110 ==> AES128 with Key7[127:0] 1111 ==> AES128 with Key8[127:0]

It can be seen that the image information: such as the Image Version of the anti-rollback function, whether the Image is AES encrypted, which type of AES (CBC/CTR/ECB, 128/256) encryption is used, the IV value used for encryption, and which OTP is used. An AES key is stored in this 32-byte appended data. During the system startup process, the boot code at each stage performs corresponding version check and decryption image based on the appended data in the boot code image of the next stage.

4. The principles of preventing error injection and signal analysis¶

Features to prevent error injection and signal analysis such as Multiple Round, SCA, key2sha1. This function is turned off by default and needs to be turned on by configuring OTP (SeeOTP Usage Reference for details).

Multiple Round, indicating that AES internal encryption and decryption needs to be performed N (1~4) times, and the results of N times are consistent and then output.

The hardware adds the function of Multiple Rounds. If this function is turned on, after the hardware completes one AES encryption and decryption, it will record the result and internally re-do AES encryption and decryption ½/3 times (depending on the Register settings), and compare N results. If one result is inconsistent, it is determined that the result is wrong, and the AESDMA Engine does not output the result, thereby preventing hacker attacks. It has been measured that after this function is turned on, the AES encryption rate will drop slightly, and it can be turned on by configuring OTP.
SCA adds random num to aes encryption and decryption to disrupt aes timing to prevent SCA attacks.

Side Channel Analysis (SCA) is a new cryptanalysis method that breaks through the traditional cryptanalysis thinking mode and uses various physical information (such as power consumption, electromagnetic radiation, sound, visible light, etc.) leaked during the chip cryptographic operation and the correlation between encryption and decryption operations to crack the cryptographic system.

AESDMA Engine can increase the complexity of AES encryption and decryption by adding redundant operations when performing AES encryption and decryption, making it impossible for attackers to use tools to infer and analyze the number of rounds of encryption and decryption based on the principles of AES encryption and decryption. This function is transparent to the software and can be enabled by configuring OTP.
key2sha1

The HW Flow and principle of this solution are as follows:
1. When burning the OTP of AESKEY/RSAKEY/PASSWORD, the user needs to calculate SHA1 of AESKEY/RSAKEY/PASSWORD respectively, and XOR the SHA1 result into 32-bit data and write it into OTP_KeyX_chk/OTP_RSA_KEY_N_CHK/OTP_PassWord_chk.
2. During the system startup process, HW Auto Load AESKEY into the AESDMA Engine and RSAKey into the SRAM of RSA_ENG, and then start the AES/RSA operation. If OTP_RSA_KEY_N_CHK_ENABLE/OTP_OTP_KEY_CHK_ENABLE/OTP_PASSWORD_CHK_ENABLE is turned on, the ROM code will perform sha1&xor action on rsakey/aeskey/pwd, and the result will be consistent with the SHA1&XOR' result saved by the user in OTP, which proves that the key has not been modified.
The specific behavior of ROM code is as follows:

Figure 6: key2sha1 schematic diagram
1. OTP_PROTECT_ENABLE is the main switch, sub-switches RSA_N_CHK_ENABLE, AES_CHK_ENABLE, PWD_CHK_ENABLE
2. When the pre-switch is satisfied, the ROM code performs a SHA1 operation on PWD/AESKEY/RSAKEY, and then performs 5 sets of XOR operations on the results of the sha1 operation (160bit) to obtain the final result of 32bit data.
3. The 32 bits in step 2 will be compared with the value stored in the OTP. If they are consistent, the verification is considered to be passed, otherwise it will be Halt.

5. Security_boot_tools Usage¶

The main steps to use Security_boot_tools to sign an alkaid image are as follows:

Compile and package first to generate an unsigned complete image burning package.
Manually make the RSA key and aes Key and replace the default RSA key and aes Key in the Security_boot_tools directory.
Compile the configuration file sign_image.config and specify the Image version/rsa key/aes key/aes encryption mode (CBC/CTR/ECB)/aes IV value and other information of the boot Image at each stage.
Execute Security_boot_tools to automatically complete the unpacking, signing, embedding CUST Key, appended data, packaging, compression, etc. of the complete image burning package based on the configuration information, and output the signed complete image burning package.

5.1. Make RSA key and aes Key¶

5.1.1 Make RSA Key¶

The production method is suitable for RSA Key in OTP Key/CUST Key/Image Key. According to customer needs, multiple images can use the same Key or multiple Images can use different RSA Keys. For security reasons, it is recommended to use multiple different RSA keys.

Please use the openssl commands to generate Private.bin and Public.bin.OpenSSL is a commonly used open-source encryption library and command-line toolset in Linux systems. Its core functions include providing secure communication, data encryption/decryption, digital signatures, and certificate management. It is recommended to use version 3.0.17 or above.

The E key value generated by the following command defaults to 0x10001, and security boot flow does not support custom E key values.

RSA2048:

Generate RSA private key
```
openssl genrsa -out private.pem 2048
```

Generate RSA public key

openssl rsa -in private.pem -out public.pem -outform PEM -pubout

RSA4096:

Generate RSA private key
```
openssl genrsa -out private.pem 4096
```

Generate RSA public key

openssl rsa -in private.pem -out public.pem -outform PEM -pubout

Just replace the n pairs of RSA keys generated above with the corresponding key binary files in the rsa2048 or rsa4096 directory under project/image/security_boot_tools/.

key type	Description
private-otp.pem	Used by security_boot_tools to sign IPL
public-otp.pem	Needs to be manually burned into OTP for startup process ROM code verification IPL
private-cust.pem	Used by security_boot_tools to sign IPL_CUST/TF_A/OPTEE
public-cust.pem	Embedded into IPL by security_boot_tools, used for IPL verification during startup IPL_CUST/TF_A/OPTEE
private-image.pem	Used by security_boot_tools to sign other images except IPL/IPL_CUST/TF_A/OPTEE
public-image.pem	Embedded into IPL_CUST by security_boot_tools, used for startup process IPL_CUST verification other than IPL/IPL_CUST/TF_A/OPTEE Image

5.1.2. Making AES Key¶

Here, xxd tool（The command-line binary file analysis tool pre-installed in Linux, whose function here is to convert hexadecimal back to a binary file.） is used to generate AES key binary file. The production method is suitable for 8 aes-128 keys or 4 aes-256 keys in OTP. According to customer needs, multiple images can use the same aes key or multiple images can use different aes keys. For security reasons, it is recommended to use multiple different aes keys.

AES-128 Key

echo '00102030405060708090A0B0C0D0E0FF' | xxd -r -ps > aesKey_128.bin

AES-256 Key

echo '000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F' | xxd -r -ps > aesKey_256.bin

IV

echo '303132333435363738393A3B3C3D3E3F' | xxd -r -ps > IV.bin

Just replace the n AES keys generated above with the corresponding key binary files that need to be used in the aesKey directory under project/image/security_boot_tools/.

5.2. sign_image.config¶

Enter project/image/security_boot_tools/ and modify the sign_image.config file.

Parameter description in sign_image.config file:

Name	Description
rsalen	The value of rsalen is 2048 or 4096. The boot code of each stage is specified by this parameter, RSA2048 or RSA4096
ipl_abk	IPL image version number, anti-rollback func used, when ipl_abk=0 means antirollback is not used
ipl_aeskeynum	IPL encryption function. There are 8 aes128 and 4 aes256 in the aeskey directory. You can choose to use one of the 4 aes256 and 8 aes128, and use it with aeskeylen. When ipl_aeskeynum=0, it means that aes encryption is not used. Taking ipl_aeskeylen=128&&ipl_aeskeynum=1 as an example, it shows that IPL will use security_boot_tools/aeskey/aesKey128_1.bin as aes-key for encryption
ipl_aeskeylen	IPL encryption function. There are 8 aes128 and 4 aes256 in the aeskey directory, and the value of aeskeylen is 128 or 256. When ipl_aeskeylen=0, it means that aes encryption is not used and is used in conjunction with ipl_aeskeynum.
ipl_IV	The IPL encryption method must be cbc. If encrypted, fill in this item with the name of the IV’s binary

sw_debug	Used instead of OTP_Secure_boot during testing, debug mode

ipl_cust_abk	IPL_CUST version number, antirollback func used

add_sbot_header	sboot can choose whether to add the Image header, which is turned off by default

tf_a_abk	TF_A version number, antirollback func used
tf_a_aes_type	tf_a encryption method (supports ecb cbc ctr), if you select CBC or CTR, you need an IV value
tf_a_aeskeylen	The value of aeskeylen is 128 or 256. When tf_a_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with tf_a_aeskeynum
tf_a_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When tf_a_aeskeynum=0, it means that aes encryption is not used
tf_a_IV	IV value required by CBC or CTR file name
tf_a_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

optee_abk	OPTEE version number, antirollback func used
optee_aes_type	Optee encryption method (supports ecb cbc ctr), if you choose CBC or CTR, you need an IV value
optee_aeskeylen	The value of aeskeylen is 128 or 256. When optee_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with optee_aeskeynum
optee_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When optee_aeskeynum=0, it means that aes encryption is not used
optee_IV	IV value filename required by CBC or CTR
optee_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

Name	Description
vmm_abk	VMM version number, antirollback func used, version control is not supported yet
vmm_aes_type	Encryption method (supports ecb cbc ctr), if you select CBC or CTR, you need an IV value
vmm_aes_enable	Whether VMM uses AES encryption. If it is 0, it means aes encryption is not applicable
vmm_aeskeylen	The value of aeskeylen is 128 or 256. When vmm_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with vmm_aeskeynum
vmm_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When vmm_aeskeynum=0, it means that aes encryption is not used
vmm_IV	IV value file name required by CBC or CTR
vmm_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

uboot_abk	uboot version number, antirollback func used
uboot_aes_type	Encryption method (supports ecb cbc ctr), if you select CBC or CTR, you need an IV value
uboot_aeskeylen	The value of aeskeylen is 128 or 256. When uboot_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with uboot_aeskeynum
uboot_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When uboot_aeskeynum=0, it means that aes encryption is not used
uboot_IV	IV value file name required by CBC or CTR
uboot_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

kernel_abk	kernel version number, antirollback func used
kernel_aes_type	Encryption method (supports ecb cbc ctr), if you select CBC or CTR, you need an IV value
kernel_aeskeylen	The value of aeskeylen is 128 or 256. When kernel_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with kernel_aeskeynum
kernel_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When kernel_aeskeynum=0, it means that aes encryption is not used
kernel_IV	IV value file name required by CBC or CTR
kernel_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

Name	Description
rtos_abk	RTOS version number, antirollback func used, version control is not supported yet
rtos_aes_type	Encryption method (supports ecb cbc ctr), if CBC or CTR is selected, IV value is required
rtos_aeskeylen	The value of aeskeylen is 128 or 256. When rtos_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with rtos_aeskeynum
rtos_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When rtos_aeskeynum=0, it means that aes encryption is not used
rtos_IV	IV value required by CBC or CTR file name
rtos_enable	Whether to enable the above parameters, if it is 0, the image parameters will be used by default

image_aes_type	Encryption method (supports ecb cbc ctr), if CBC or CTR is selected, IV value is required
image_aeskeylen	The value of aeskeylen is 128 or 256. When image_aeskeylen=0, it means that aes encryption is not used, and it is used in conjunction with image_aeskeynum
image_aeskeynum	The valid range of aeskeynum under aeskeylen=128 is [1-8]. The valid range of aeskeynum under aeskeylen=256 is [1-4]. When image_aeskeynum=0, it means that aes encryption is not used.
image_IV	IV value required by CBC or CTR file name
image_abk	Pre-reserved, if using the anti rollback function, fill in the abk of the corresponding image

5.3. Run Security_boot_tools¶

The actual steps are as follows:

Enter the project directory, make xxx_defconfig; make clean -j32; make image -j32;
Enter project/image/security_boot_tools/ and run make clean;make; to generate the security_boot_tools/image_secure directory (Image in the directory has been signed)

If the signing action needs to be done in another directory or on a different computer, please run make image_prepare in Step 2, copy the complete security_boot_tools to another location, and then run make.

Note: For images generated by security_boot_tools, estar will automatically configure bootcmd to verify (or decrypt + verify) the kernel. By default, rootfs will be signed, but bootcmd will not verify the signature (or decrypt + verify the signature) of the rootfs. If you need to verify the rootfs signature, please manually modify the bootcmd and add the signature verification rootfs step.

5.4. Signature cmd¶

In the Uboot stage, the environment variable bootcmd needs to be modified to verify the binary such as Linux Kernel/rtos/vmm/ramdiskfs. The principle is to use the sigauth command to verify and decrypt the binary:

sigauth <Binary_Addr> <KEY_Addr> [--aes]

<Binary_Addr>: The loading address of the binary that needs to be verified (or encrypted) in ddr.
<KEY_Addr>: The loading address of IPL_CUST in ddr. sigauth cmd will find the public N key inside IPL_CUST based on the IPL_CUST header information. Generally, IPL_CUST is loaded at position 0x21000000 during the startup process.
[--aes]: Optional, indicating whether to decrypt the binary with AES before verifying the signature. sigauth cmd will automatically find the specified OTP AES key and the specified AES decryption mode based on the binary appended data.

U-boot starts pure linux, before signature verification:

EX:
setenv bootcmd ' dcache on; loados nand 0x23000000 KERNEL ${kernel_file_size}; bootm 0x23000000; dcache on; loados nand 0x23000000 RECOVERY ${recovery_file_size}; bootm 0x23000000;

U-boot starts pure linux, after signature verification:

EX:
setenv bootcmd ' dcache on; loados nand 0x23000000 KERNEL ${kernel_file_size}; sigauth 23000000 0x21000000; bootm 0x23000000; dcache on; loados nand 0x23000000 RECOVERY ${recovery_file_size}; bootm 0x23 000000;

If the image uses encryption, please add --aes at the end of the sigauth command in the corresponding startup mode.

U-boot starts dualos, before signature verification:

EX:
setenv bootcmd ' loados nand by_header MISC by_header; loados nand by_header RTOS by_header;bootm start ${loados_addr};bootm loados;bootm prep;wakeupcpu 3 s 0x2ef08000; loados nand by_header RAMDISK by_header; loados nand by_header KERNEL by_header;dcache off;bootm $ {loados_addr};

U-boot starts dualos, after signature verification:

EX:
setenv bootcmd ' loados nand by_header MISC by_header; loados nand by_header RTOS by_header;sigauth ${loados_addr} 0x21000000;bootm start ${loados_addr};bootm loados;bootm prep;wakeupcpu 3 s 0x2ef08000; loados nand by_header RAMDISK by_header;sigauth ${ loados_addr } 0x21000000; loados nand by_header KERNEL by_header;sigauth ${loados_addr} 0x21000000;dcache off;bootm ${loados_addr};

Set rootfs_size in ENV:

rootfs_size <rootfs_sieze>; saveenv;
EX:
rootfs_size 1af100; saveenv;

After reading rootfs on the corresponding storage medium, add:

dcache off;sigauth <Binary_Addr> <KEY_Addr> [--aes];dcache on;
EX:
setenv bootcmd ' dcache off; loados nand 0x22000000 roofs 0x600000; sigauth 22000000 0x21000000 ; loados nand 0x23000000 KERNEL ${kernel_file_size};sigauth 23000000 0x21000000; dcache on; bootm 0x23000000; loados nand 0x23000000 RECOVERY ${recovery_file_size}; bootm 0x23000000;

6. Security BOOT Deployment Steps¶

OTP can only be programmed once. Once programmed, it cannot be cleared and re-flashed. In order to prevent misoperation from causing the system to fail to start or even the IC to become invalid, it is generally recommended to proceed with the formal OTP process only after the debugging process PASS. That is, first burn part of the OTP for testing, confirm the debugging process PASS, and then burn the remaining OTP later.

In debugging mode, Security_boot_tools will set the AUTH column position in the IPL header to 1, rom code loads IPL, IPL loads IPL_CUST/TF-A/OPTEE, IPL_CUST loads VMM/RTOS/LINUX, and the signature verification startup process is determined based on the AUTH mark.

In OTP official mode, rom code loads IPL, IPL loads IPL_CUST/TF-A/OPTEE, and IPL_CUST loads VMM/RTOS/LINUX. The signature verification startup process will be decided based on whether the OTP is burned with the OTP_SECURITY_BOOT mark.

6.1. Security Boot Debugging Process¶

Step 1: Users generate three sets of RSA public/private keys by themselves and replace the key files in the security_boot_tools/aes/ and rsa2048 or rsa4096/ directories. For details, see 5.1. Making RSA key and aes Key.

Step 2: Use U-Boot Command otpctrl to burn RSA Public NKey/Ekey (or AES Key). For details, see OTP Usage Reference.

It is recommended to only burn OTP_RSA_N / OTP_RSA_E / OTP_RSA_KEY_LEN / OTP_KEY1~8 during the debugging phase.
It is not recommended to burn the OTP_SECURITY_BOOT field. Even if the OTP content is burned by mistake during the debugging stage, the chip board cannot start the signed image, but it can still be used to start the unsigned image.
It is not recommended to burn all OTP LOCK & BLOCK fields. Even if the OTP content is burned by mistake during the debugging stage, there is still a chance to check and modify the OTP content.
It is not recommended to burn OTP_ROM_SELECT_AES_KEY. Even if the OTP AES-key content is mistakenly burned during the debugging stage, the ROM code can still start the unencrypted signed IPL.

Step 3: Configure the security_boot_tools configuration file sign_image.config according to customer needs, but the following configurations need to be noted during the debugging phase:

sw_debug=1 #Even if the OTP does not burn the OTP_SECURITY_BOOT field, the system startup process will also go through the security boot signature verification and decryption process.
ipl_aeskeynum=0 #Because OTP does not burn OTP_ROM_SELECT_AES_KEY, the system startup process will not decrypt IPL, so security_boot_tools is not used to encrypt IPL.
ipl_aeskeylen=0

Step 4: Check system printing

Check the system printout to confirm that ROM->IPL->IPL_CUST->U-Boot has progressed to the flow of SecurityBoot.

ROM->IPL confirms whether to use SecurityBoot method

If the ROM signature verification IPL is successful, there will be no log, but if the signature verification fails, AUTH ERR will be printed (the baud rate may need to be adjusted to 38400 or 57600, otherwise garbled characters will be printed).
IPL->IPL_CUST->U-Boot confirms whether to use SecurityBoot method

Just check the log. It usually contains the Authenticate image keyword. If the decryption process is enabled, there will also be the AES ECB keyword.

Examples are as follows:
U-Boot -> kernel confirms whether to use SecurityBoot method

Directly check whether bootcmd has a signature verification signature. For details, see 5.4. Signature cmd.

6.2. Security Boot Formal Process¶

After debugging mode can run normally after Security boot is started, it means that the steps of burning OTP RSA N/E KEY and AES KEY in the debugging stage are reliable. Subsequent chips can directly copy the OTP burning commands summarized in debugging mode.

The formal process only requires supplementary burning of some OTP fields.

Step 1: Use U-Boot Command otpctrl to burn OTP_SECURITY_BOOT, RSA KEY's LOCK and BLOCK, OTP_ROM_SELECT_AES_KEY, etc.

Step 2: Configure the security_boot_tools configuration file sign_image.config:

sw_debug = 0
ipl_aeskeynum = 1 #For example, use the first AES-128 KEY
ipl_aeskeylen = 128

Step 3: Check System Printing

After burning, follow the same method as in 7.1 to confirm that ROM->IPL->IPL_CUST->U-Boot->Kernel has reached SecurityBoot and can boot to U-Boot. Then, ROM->IPL->IPL_CUST->U- Boot->Kernel's SecurityBoot flow and OTP related verification have been PASS.