HAB

HAB (High Assurance Boot) provides a mechanism to ensure that the running software can be trusted. Nxpimage application is used for generation of HAB container including CSF data and image encryption(if applicable). It is an actual successor of legacy elftosb and CST tools.

Compared to other SPSDK image types, the HAB container configuration is stored in BD configuration files. The main reason for it is keeping the backwards compatibility with legacy elftosb and CST tools. BD configuration file instructs nxpimage how the image and CSF data will look like.

There are three supported types of images:

• plain

• authenticated

• encrypted

Examples

HAB Export

nxpimage hab export --command "path\to\config\file.bd" --output path\to\output.bin

HAB Parse

nxpimage hab parse --binary "path\to\output.bin" path\to\output\dir

Configuration file types

Example of Plain BD config

 options {
     flags = 0x00;
     startAddress = 0x2024ff00;
     ivtOffset = 0x0;
     initialLoadSize = 0x100;

     entryPointAddress = 0x202629e1;
 }

 sources {
     elfFile = extern(0);
 }

 section (0) {
 }

Example of Authenticated BD config

 options {
     flags = 0x08;
     startAddress = 0x1000;
     ivtOffset = 0x1000;
     initialLoadSize = 0x2000;
     entryPointAddress = 0x34e1;
 }

 sources {
     elfFile = extern(0);
 }

 constants {
     SEC_CSF_HEADER              = 20;
     SEC_CSF_INSTALL_SRK         = 21;
     SEC_CSF_INSTALL_CSFK        = 22;
     SEC_CSF_INSTALL_NOCAK       = 23;
     SEC_CSF_AUTHENTICATE_CSF    = 24;
     SEC_CSF_INSTALL_KEY         = 25;
     SEC_CSF_AUTHENTICATE_DATA   = 26;
     SEC_CSF_INSTALL_SECRET_KEY  = 27;
     SEC_CSF_DECRYPT_DATA        = 28;
     SEC_NOP                     = 29;
     SEC_SET_MID                 = 30;
     SEC_SET_ENGINE              = 31;
     SEC_INIT                    = 32;
     SEC_UNLOCK                  = 33;
 }

 section (SEC_CSF_HEADER;
     Header_Version="4.2",
     Header_HashAlgorithm="sha256",
     Header_Engine="ANY",
     Header_EngineConfiguration=0,
     Header_CertificateFormat="x509",
     Header_SignatureFormat="CMS"
     )
 {
 }

 section (SEC_CSF_INSTALL_SRK;
     InstallSRK_Table="gen_hab_certs\SRK_hash.bin",
     InstallSRK_SourceIndex=0
     )
 {
 }

 section (SEC_CSF_INSTALL_CSFK;
     InstallCSFK_File="crts\CSF1_1_sha256_2048_65537_v3_usr_crt.pem",
     InstallCSFK_CertificateFormat="x509"
     )
 {
 }

 section (SEC_CSF_AUTHENTICATE_CSF)
 {
 }

 section (SEC_CSF_INSTALL_KEY;
     InstallKey_File="crts\IMG1_1_sha256_2048_65537_v3_usr_crt.pem",
     InstallKey_VerificationIndex=0,
     InstallKey_TargetIndex=2)
 {
 }

 section (SEC_CSF_AUTHENTICATE_DATA;
     AuthenticateData_VerificationIndex=2,
     AuthenticateData_Engine="ANY",
     AuthenticateData_EngineConfiguration=0)
 {
 }

 section (SEC_SET_ENGINE;
     SetEngine_HashAlgorithm = "sha256",
     SetEngine_Engine = "ANY",
     SetEngine_EngineConfiguration = "0")
 {
 }

 section (SEC_UNLOCK;
     Unlock_Engine = "SNVS",
     Unlock_features = "ZMK WRITE"
     )
 {
 }

Example of Encrypted BD config

 options {
     flags = 0x0c;
     startAddress = 0x80001000;
     ivtOffset = 0x400;
     initialLoadSize = 0x1000;
     DCDFilePath = "dcd_files\evkmimxrt1166_SDRAM_dcd.bin";
     entryPointAddress = 0x800041f5;
 }

 sources {
     elfFile = extern(0);
 }

 constants {
     SEC_CSF_HEADER              = 20;
     SEC_CSF_INSTALL_SRK         = 21;
     SEC_CSF_INSTALL_CSFK        = 22;
     SEC_CSF_INSTALL_NOCAK       = 23;
     SEC_CSF_AUTHENTICATE_CSF    = 24;
     SEC_CSF_INSTALL_KEY         = 25;
     SEC_CSF_AUTHENTICATE_DATA   = 26;
     SEC_CSF_INSTALL_SECRET_KEY  = 27;
     SEC_CSF_DECRYPT_DATA        = 28;
     SEC_NOP                     = 29;
     SEC_SET_MID                 = 30;
     SEC_SET_ENGINE              = 31;
     SEC_INIT                    = 32;
     SEC_UNLOCK                  = 33;
 }

 section (SEC_CSF_HEADER;
     Header_Version="4.2",
     Header_HashAlgorithm="sha256",
     Header_Engine="ANY",
     Header_EngineConfiguration=0,
     Header_CertificateFormat="x509",
     Header_SignatureFormat="CMS"
     )
 {
 }

 section (SEC_CSF_INSTALL_SRK;
     InstallSRK_Table="gen_hab_certs\SRK_hash.bin",
     InstallSRK_SourceIndex=0
     )
 {
 }

 section (SEC_CSF_INSTALL_CSFK;
     InstallCSFK_File="crts\CSF1_1_sha256_2048_65537_v3_usr_crt.pem",
     InstallCSFK_CertificateFormat="x509"
     )
 {
 }

 section (SEC_CSF_AUTHENTICATE_CSF)
 {
 }

 section (SEC_CSF_INSTALL_KEY;
     InstallKey_File="crts\IMG1_1_sha256_2048_65537_v3_usr_crt.pem",
     InstallKey_VerificationIndex=0,
     InstallKey_TargetIndex=2)
 {
 }

 section (SEC_CSF_AUTHENTICATE_DATA;
     AuthenticateData_VerificationIndex=2,
     AuthenticateData_Engine="ANY",
     AuthenticateData_EngineConfiguration=0)
 {
 }

 section (SEC_CSF_INSTALL_SECRET_KEY;
     SecretKey_Name="gen_hab_encrypt\evkmimxrt1064_iled_blinky_SDRAM_hab_dek.bin",
     SecretKey_Length=256,
     SecretKey_VerifyIndex=0,
     SecretKey_TargetIndex=0)
 {
 }

 section (SEC_CSF_DECRYPT_DATA;
     Decrypt_Engine="ANY",
     Decrypt_EngineConfiguration="0",
     Decrypt_VerifyIndex=0,
     Decrypt_MacBytes=16)
 {
 }

Additional configuration parameters

Although the nxpimage application fully supports legacy elftosb configuration files, the support of some new optional parameters has been added.

Newly added BD configuration parameters:

Name	BD Section	Example	Description
signatureTimestamp	options	signatureTimestamp = “11/05/2023 11:58:00”;	Timestamp of generated signature
AuthenticateCsf_PrivateKeyFile	SEC_CSF_AUTHENTICATE_CSF	AuthenticateCsf_PrivateKeyFile=”keys/CSF1_1_sha256_2048_65537_v3_usr_key.pem”	Path to authenticate CSF private key file. If not set, the file will be determined from InstallCSFK_File parameter
AuthenticateData_PrivateKeyFile	SEC_CSF_AUTHENTICATE_DATA	AuthenticateData_PrivateKeyFile=”keys/IMG1_1_sha256_2048_65537_v3_usr_key.pem”	Path to authenticate IMG private key file. If not set, the file will be determined from InstallKey_File parameter
SecretKey_ReuseDek	SEC_CSF_INSTALL_SECRET_KEY	SecretKey_ReuseDek=true	If set, the secret key from SecretKey_Name parameter will be used. If not, a random key will be generated and stored.
Decrypt_Nonce	SEC_CSF_DECRYPT_DATA	Decrypt_Nonce=”gen_hab_encrypt/nonce.bin”	If set, the nonce from the given file will be used. If not, a random nonce will be generated.