View source for High Assurance Boot MX8 Sections

= Code signing step by step instructions =

== Code signing step by step instructions i.MX8M==
<section begin=NXP_DOC_habv4/>
NXP Provides documentation for enabling HAB for the i.MX8M Family. The information in this wiki is derived from NXP's documentation.

The U-Boot source code provides a directory with documentation and examples: {{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/habv4/

The following documentation is helpful to review:

* U-Boot [{{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/habv4/introduction_habv4.txt doc/imx/habv4/introduction_habv4.txt]
* U-Boot [{{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/habv4/guides/mx8m_secure_boot.txt doc/imx/habv4/guides/mx8m_secure_boot.txt]
* NXP AN12263 [https://www.nxp.com/docs/en/application-note/AN12263.pdf HABv4 RVT Guidelines and Recommendations]
<section end=NXP_DOC_habv4/>

== Code signing step by step instructions i.MX8==
<section begin=NXP_DOC_ahab/>
NXP Provides documentation for enabling AHAB for the i.MX8 Family. The information in this wiki is derived from NXP's documentation.

The U-Boot source code provides a directory with documentation and examples: {{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/ahab/

The following documentation is helpful to review:

* U-Boot [{{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/ahab/introduction_ahab.txt doc/imx/ahab/introduction_ahab.txt]
* U-Boot [{{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/ahab/guides/mx8_mx8x_spl_secure_boot.txt doc/imx/ahab/guides/mx8_mx8x_spl_secure_boot.txt]
* U-Boot [{{#var:U-BOOT_GIT_HTTP}}/blob/imx_v2020.04_5.4.70_2.3.2_var01/doc/imx/ahab/guides/mx8_mx8x_secure_boot.txt doc/imx/ahab/guides/mx8_mx8x_secure_boot.txt]
* NXP AN12312 [https://www.nxp.com/docs/en/application-note/AN12312.pdf Secure Boot on i.MX 8 and i.MX 8X Families using AHAB]
<section end=NXP_DOC_ahab/>

= Generate PKI =

== Generate PKI i.MX8M ==
<section begin=HAB_PKI_habv4/>
 $ ./hab4_pki_tree.sh
And complete the interactive questions. For example: 
 Do you want to use an existing CA key (y/n)?: n
 Do you want to use Elliptic Curve Cryptography (y/n)?: n
 Enter key length in bits for PKI tree: 4096
 Enter PKI tree duration (years): 20
 How many Super Root Keys should be generated? 4
 Do you want the SRK certificates to have the CA flag set? (y/n)?: y

Generate Super Root Key (SRK) table
 $ cd ../crts/
 $ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e SRK_1_2_3_4_fuse.bin -d sha256 -c ./SRK1_sha256_4096_65537_v3_ca_crt.pem,./SRK2_sha256_4096_65537_v3_ca_crt.pem,./SRK3_sha256_4096_65537_v3_ca_crt.pem,./SRK4_sha256_4096_65537_v3_ca_crt.pem -f 1
<section end=HAB_PKI_habv4/>

== Generate PKI i.MX8 ==
<section begin=HAB_PKI_ahab/>
 $ ./ahab_pki_tree.sh
And complete the interactive questions. For example: 
 Do you want to use an existing CA key (y/n)?: n
 Do you want to use Elliptic Curve Cryptography (y/n)?: n
 Enter key length in bits for PKI tree: 4096
 Enter the digest algorithm to use: sha384
 Enter PKI tree duration (years): 20
 Do you want the SRK certificates to have the CA flag set? (y/n)?: n

Generate Super Root Key (SRK) table
 $ cd ../crts/
 $ ../linux64/bin/srktool -a -s sha384 -t SRK1234table.bin -e SRK1234fuse.bin -f 1 -c SRK1_sha384_4096_65537_v3_usr_crt.pem,SRK2_sha384_4096_65537_v3_usr_crt.pem,SRK3_sha384_4096_65537_v3_usr_crt.pem,SRK4_sha384_4096_65537_v3_usr_crt.pem
 $ ll SRK1234*
 -rw-rw-r-- 1 nate nate   64 Sep 15 14:47 SRK1234fuse.bin
 -rw-rw-r-- 1 nate nate 2112 Sep 15 14:47 SRK1234table.bin
<section end=HAB_PKI_ahab/>

== Generate PKI i.MX9 ==
<section begin=HAB_PKI_ahab_ecc/>
 $ ./ahab_pki_tree.sh
And complete the interactive questions. For example: 
 Do you want to use an existing CA key (y/n)?: n
 Key type options (confirm targeted device supports desired key type):
 Select the key type (possible values: rsa, rsa-pss, ecc)?: ecc
 Enter length for elliptic curve to be used for PKI tree:
 Possible values p256, p384, p521: p384
 Enter the digest algorithm to use: sha384
 Enter PKI tree duration (years): 20
 Do you want the SRK certificates to have the CA flag set? (y/n)?: n

{{note| Info:<br>
The parameters of the elliptical curve and digest algorithm correspond to some extent. In our Variscite reference PKI tree, we're using ECDSA-384 along with the Signature Digest algorithm sha384 to match them both.
If you would like to use other parameters as given here, please review the available documentation to check what is supported by the specific SoC.
|info}}

Generate Super Root Key (SRK) table
 $ cd ../crts/
 $ ../linux64/bin/srktool -a -d sha256 -s sha384 -t SRK1234table.bin -e SRK1234fuse.bin -f 1 -c SRK1_sha384_secp384r1_v3_usr_crt.pem,SRK2_sha384_secp384r1_v3_usr_crt.pem,SRK3_sha384_secp384r1_v3_usr_crt.pem,SRK4_sha384_secp384r1_v3_usr_crt.pem
 $ ll SRK1234*
 -rw-rw-r-- 1 nate nate   64 Sep 15 14:47 SRK1234fuse.bin
 -rw-rw-r-- 1 nate nate 2112 Sep 15 14:47 SRK1234table.bin

{{note| Note:<br>
For the SoC i.MX93, the Message Digest algorithm (option —d) is sha256, while the Signature Digest algorithm (option -s) must match the one from the PKI generation.
|warning}}
<section end=HAB_PKI_ahab_ecc/>

= Program the SRK (public keys) to the SOC e-fuses =

== Program the SRK (public keys) to the SOC e-fuses i.MX8M==
<section begin=UBOOT_CMDS_habv4/>
'''SRK_1_2_3_4_fuse.bin.u-boot-cmds:'''
 $ cat build_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}/SRK_1_2_3_4_fuse.bin.u-boot-cmds
 # Note: These are One-Time Programmable e-fuses. Once you write them you can't go back, so get it right the first time.
 
 fuse prog -y 6 0 0xDA6B9ADB
 fuse prog -y 6 1 0xDC9B55A1
 fuse prog -y 6 2 0x93D10134
 fuse prog -y 6 3 0x5CDC8DA3
 fuse prog -y 7 0 0x143709F8
 fuse prog -y 7 1 0xC6E305A7
 fuse prog -y 7 2 0x3E718DA2
 fuse prog -y 7 3 0xC6AC85B6
 
 # After the device successfully boots a signed image without generating any HAB events, it is safe to secure, or 'close', the device.
 # This is the last step in the process. Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.
 # Important notes:
 # - This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.
 # - If anything in the previous steps wasn't done correctly, the SOM will not boot after writing this bit.
 
 fuse prog 1 3 0x02000000
<section end=UBOOT_CMDS_habv4/>

== Program the SRK (public keys) to the SOC e-fuses i.MX8QM==
<section begin=UBOOT_CMDS_ahab_mx8qm/>
'''SRK1234fuse.bin.u-boot-cmds:'''
 $ cat build_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}/SRK1234fuse.bin.u-boot-cmds
 # Note: These are One-Time Programmable e-fuses. Once you write them you can't go back, so get it right the first time.
 
 fuse prog -y 0 722 0xC7CD8343
 fuse prog -y 0 723 0x9DAD444
 fuse prog -y 0 724 0xCA69438A
 fuse prog -y 0 725 0xF58BCA5A
 fuse prog -y 0 726 0xD9B0C333
 fuse prog -y 0 727 0xFB085CFC
 fuse prog -y 0 728 0xAC6977BD
 fuse prog -y 0 729 0x547DD584
 fuse prog -y 0 730 0xD7D99422
 fuse prog -y 0 731 0x8DD76A21
 fuse prog -y 0 732 0xA4BFC709
 fuse prog -y 0 733 0x176D4CB9
 fuse prog -y 0 734 0x29432F99
 fuse prog -y 0 735 0xF5DA795E
 fuse prog -y 0 736 0xD7A20D12
 fuse prog -y 0 737 0x73CA2F0C
 
 # After the device successfully boots a signed image without generating any HAB events, it is safe to secure, or 'close', the device.
 # This is the last step in the process. Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.
 # Important notes:
 # - This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.
 # - If anything in the previous steps wasn't done correctly, the SOM will not boot after writing this bit.
 
 ahab_close
<section end=UBOOT_CMDS_ahab_mx8qm/>

== Program the SRK (public keys) to the SOC e-fuses i.MX8QXP==
<section begin=UBOOT_CMDS_ahab_mx8qxp/>
'''SRK1234fuse.bin.u-boot-cmds:'''
 $ cat build_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}/SRK1234fuse.bin.u-boot-cmds
 # Note: These are One-Time Programmable e-fuses. Once you write them you can't go back, so get it right the first time.
 
 fuse prog -y 0 730 0xC7CD8343
 fuse prog -y 0 731 0x9DAD444
 fuse prog -y 0 732 0xCA69438A
 fuse prog -y 0 733 0xF58BCA5A
 fuse prog -y 0 734 0xD9B0C333
 fuse prog -y 0 735 0xFB085CFC
 fuse prog -y 0 736 0xAC6977BD
 fuse prog -y 0 737 0x547DD584
 fuse prog -y 0 738 0xD7D99422
 fuse prog -y 0 739 0x8DD76A21
 fuse prog -y 0 740 0xA4BFC709
 fuse prog -y 0 741 0x176D4CB9
 fuse prog -y 0 742 0x29432F99
 fuse prog -y 0 743 0xF5DA795E
 fuse prog -y 0 744 0xD7A20D12
 fuse prog -y 0 745 0x73CA2F0C
 
 fuse read 0 730 16
 Reading bank 0:
 
 Word 0x000002da: c7cd8343 09dad444 ca69438a f58bca5a
 Word 0x000002de: d9b0c333 fb085cfc ac6977bd 547dd584
 Word 0x000002e2: d7d99422 8dd76a21 a4bfc709 176d4cb9
 Word 0x000002e6: 29432f99 f5da795e d7a20d12 73ca2f0c
 
 # After the device successfully boots a signed image without generating any HAB events, it is safe to secure, or 'close', the device.
 # This is the last step in the process. Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.
 # Important notes:
 # - This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.
 # - If anything in the previous steps wasn't done correctly, the SOM will not boot after writing this bit.
 
 ahab_close
<section end=UBOOT_CMDS_ahab_mx8qxp/>

== Program the SRK (public keys) to the SOC e-fuses i.MX93==
<section begin=UBOOT_CMDS_ahab_mx93/>
'''SRK1234fuse.bin.u-boot-cmds:'''
 $ cat build_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}/SRK1234fuse.bin.u-boot-cmds
 # Note: These are One-Time Programmable e-fuses. Once you write them you can't go back, so get it right the first time.
 
 fuse prog -y 16 0 0xAD78C8F5
 fuse prog -y 16 1 0xD4F88190
 fuse prog -y 16 2 0x698E25D0
 fuse prog -y 16 3 0x1408DA9D
 fuse prog -y 16 4 0x72DAF5C8
 fuse prog -y 16 5 0xDCD21ECB
 fuse prog -y 16 6 0x3F71BF59
 fuse prog -y 16 7 0x8D2D6A0F
 
 # After the device successfully boots a signed image without generating any HAB events, it is safe to secure, or 'close', the device.
 # This is the last step in the process. Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.
 # Important notes:
 # - This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.
 # - If anything in the previous steps wasn't done correctly, the SOM will not boot after writing this bit.
 
 ahab_close

One can read back the programmed e-fuses, like:
 fuse read 16 0 8   
 Reading bank 16:
 
 Word 0x00000000: ad78c8f5 d4f88190 698e25d0 1408da9d
 Word 0x00000004: 72daf5c8 dcd21ecb 3f71bf59 8d2d6a0f
<section end=UBOOT_CMDS_ahab_mx93/>

= HAB Status =

== HAB Status i.MX8M==
<section begin=HAB_STATUS_habv4/>
 Secure boot disabled
 
 HAB Configuration: 0xf0, HAB State: 0x66
 No HAB Events Found!
<section end=HAB_STATUS_habv4/>

== HAB Status i.MX8==
<section begin=HAB_STATUS_ahab/>
 Lifecycle: 0x0020, NXP closed
 
 No SECO Events Found!
<section end=HAB_STATUS_ahab/>


= Secure Device =

== Secure Device  i.MX8M==
<section begin=HAB_SECURE_habv4/>
After the device successfully boots a signed image without generating any {{#var:HAB_VERBOSE}} events, it is safe to
secure, or "close", the device.<br>
This is the last step in the process, and is completed by blowing the SEC_CONFIG[1] fuse bit.<br>
Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.<br>
<span style="color:red">'''Important notes'''</span>:<br>
- This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.<br>
- If anything in the previous steps wasn't done correctly, the SOM will not boot after writing this bit.<br>
 fuse prog 1 3 0x2000000
<section end=HAB_SECURE_habv4/>

== Secure Device  i.MX8==
<section begin=HAB_SECURE_ahab/>
After the device successfully boots a signed image without generating any {{#var:HAB_VERBOSE}} events, it is safe to
secure, or "close", the device.<br>
This is the last step in the process, and is completed by blowing a fuse.<br>
Once the fuse is blown, the chip does not load an image that has not been signed using the correct PKI tree.<br>
<span style="color:red">'''Important notes'''</span>:<br>
- This is again a One-Time Programmable e-fuse. Once you write it you can't go back, so get it right the first time.<br>
- If anything in the previous steps wasn't done correctly, the SOM will not boot after running this command.<br>
 ahab_close
<section end=HAB_SECURE_ahab/>