Skip to main content

​
Prerequisites

​
Check metabuild

Identify the correct images for signing by checking the following files in the in the metabuild.
  • <Metabuild>/<chipset>.LE.X.x/contents.xml
    This file has details about:
    • The source path of each image.
    • The format of each image (for example, pil-split or mbn).
  • <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/<chipset>_security_profile.xml
    This file provides signing-related metadata, including:
    • --image-id values.
    • A list of images that must be signed by users to ensure device security.

​
Change SecTools commands for Windows

To use SecTools commands on Windows platform, replace the <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools with <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Windows/sectools.exe.

​
Sign the images

Image signing is a security process that involves adding a cryptographic signature to a digital image. This signature serves as a unique identifier, verifying the authenticity, integrity, and origin of the image. Without image signing, there is no assurance of an image’s integrity or trusted origin, leading to potential security breaches and data loss. Follow these steps to sign the images.
  1. You can sign the images using SecTools V2. Different signing methods and secure image functionality are available. For more information see SecTools V2: Secure Image User Guide.
  2. You can generate the keys and certificates using a local signer. For more information, see Generate local (insecure) root key and certificate.
  3. To sign a single image, run the following command, where tz.mbn is used as an example.
    Note You can replace the values of OEM ID “0x1” and OEM Product ID “0xabcd” according to your requirement. 
    <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools secure-image --sign <path to tz>/trustzone_images/build/ms/bin/<flavor>/tz.mbn --image-id=TZ --security-profile <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/<chipset>_security_profile.xml --oem-id=0x1 --oem-product-id=0xabcd --anti-rollback-version=0x0 --signing-mode=LOCAL --root-certificate=./OEM-KEYS/qpsa_rootca.cer --ca-certificate=./OEM-KEYS/qpsa_attestca.cer --ca-key=./OEM-KEYS/qpsa_attestca.key --outfile ./signed_images_out/tz.mbn
    The following is a sample command for IQ-9075/IQ-9100. 
    <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools secure-image --sign <path to tz>/trustzone_images/build/ms/bin/<flavor>/tz.mbn --image-id=TZ --security-profile <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/lemans_security_profile.xml --oem-id=0x1 --oem-product-id=0xabcd --anti-rollback-version=0x0 --signing-mode=LOCAL --root-certificate=./OEM-KEYS/qpsa_rootca.cer --ca-certificate=./OEM-KEYS/qpsa_attestca.cer --ca-key=./OEM-KEYS/qpsa_attestca.key --outfile ./signed_images_out/tz.mbn
    Note Update the image path according to the path specified in the contents.xml file.
  4. Check for all images with the pil_split flag in the contents.xml file.
    Example: pil_split = "adsp" For images that should be split, use the --pil-split option.
  5. For signing the complete metabuild, use the following commands. 
    <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools metabuild-secure-image --image-finder <meta>/common/build/app/image_finder.py --sign --oem-id=0x1 --oem-product-id=0xabcd --anti-rollback-version=0x0 --signing-mode LOCAL --root-certificate=./OEM-KEYS/qpsa_rootca.cer --ca-certificate=./OEM-KEYS/qpsa_attestca.cer --ca-key=./OEM-KEYS/qpsa_attestca.key --chipset <CHIPSET_NAME> --outdir meta_signing_output/ --storage ufs
    For more information, see SecTools V2: Metabuild Secure Image User Guide.
    Note The SecTools guides are available to licensed users with authorized access.

​
Generate the signed sec.elf image

Generating a signed sec.elf image involves creating a secure executable and linkable format (ELF) file with a cryptographic signature. Signing this image ensures its authenticity, integrity, and origin. A fuse blower binary is used to permanently disable certain functionalities or components of a device for security reasons. Generating a signed sec.elf image along with a fuse blower binary involves a series of steps to ensure both the integrity of the firmware and the security of the device. To generate fuse blower binary, see SecTools V2: Fuse Blower User Guide.

​
Integrate the sample commands using SecTools

This section provides sample commands only. The following are sample commands for SecTools on Windows. Note
  • Ensure that the values such as PK hash, OEM ID, and Product ID in the command are in hexadecimal format.
  • You can replace the values of OEM ID “0x1” and OEM Product ID “0xabcd” according to your requirement.
  • You can replace the value of --fuse-pk-hash-0 with the SHA384 of OEM-KEYS/qpsa_rootca.cer.
    To calculate the correct PK hash value, use the following command: 
    openssl dgst -sha384 qpsa_rootca.cer >sha384rootcert.txt
    For more information, see Generate SHA-384 hash for RSA and ECDSA.
  • Replace the digest generated here from the user Root cert in the sec.elf generation command below.
  • Stage 1: Basic secure boot (image authentication + OEM ID + MODEL ID) Run the following command:
    QCS5430/QCS6490IQ-9075/IQ-9100IQ-8275/IQ-8300IQ-615 
    <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools fuse-blower --security-profile <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/kodiak_security_profile.xml --fuse-pk-hash-0=<sha384 of OEM-KEYS/qpsa_rootca.cer> --fuse-oem-secure-boot1-pk-hash-in-fuse --fuse-oem-secure-boot1-auth-en --fuse-oem-secure-boot2-pk-hash-in-fuse --fuse-oem-secure-boot2-auth-en --fuse-oem-secure-boot3-pk-hash-in-fuse --fuse-oem-secure-boot3-auth-en --fuse-oem-hw-id=0x0001 --fuse-oem-product-id=0xabcd --generate --sign --signing-mode=LOCAL --root-certificate=./OEM-KEYS/qpsa_rootca.cer --ca-certificate=./OEM-KEYS/qpsa_attestca.cer --ca-key=./OEM-KEYS/qpsa_attestca.key --oem-id=0x1 --oem-product-id=0xabcd --outfile basic_sec.elf
  • Stage 2: Complete secure boot (basic secure boot + debug disable + anti-rollback + write permission disable): Run the following commands.
    QCS5430/QCS6490IQ-9075/IQ-9100IQ-8275/IQ-8300IQ-615 
    <Metabuild>/<chipset>.LE.X.x/common/sectoolsv2/ext/Linux/sectools fuse-blower --security-profile <meta\>/common/sectoolsv2/kodiak_security_profile.xml --fuse-pk-hash-0=<sha384 of OEM-KEYS/qpsa_rootca.cer> --fuse-oem-secure-boot1-pk-hash-in-fuse --fuse-oem-secure-boot1-auth-en --fuse-oem-secure-boot2-pk-hash-in-fuse --fuse-oem-secure-boot2-auth-en --fuse-oem-secure-boot3-pk-hash-in-fuse --fuse-oem-secure-boot3-auth-en --fuse-oem-secure-boot-fec-enable --fuse-wdog-en --fuse-shared-qsee-spiden-disable --fuse-shared-qsee-spniden-disable --fuse-shared-mss-dbgen-disable --fuse-shared-mss-niden-disable --fuse-shared-cp-dbgen-disable --fuse-shared-cp-niden-disable --fuse-shared-ns-dbgen-disable --fuse-shared-ns-niden-disable --fuse-apps-dbgen-disable --fuse-apps-niden-disable --fuse-shared-misc-debug-disable --fuse-eku-enforcement-en --fuse-anti-rollback-feature-en=0xF --fuse-sec-key-derivation-key=0x00 --fuse-read-permissions-write-disable --fuse-oem-configuration-write-disable --fuse-secondary-key-derivation-key-read-disable --fuse-write-permissions-write-disable --fuse-public-key-hash-0-write-disable --fuse-oem-secure-boot-write-disable --fuse-secondary-key-derivation-key-write-disable --fuse-secondary-key-derivation-key-fec-enable --fuse-fec-enables-write-disable --generate --sign --fuse-oem-hw-id=0x0001 --fuse-oem-product-id=0xabcd --signing-mode=LOCAL --root-certificate=./ OEM-KEYS/qpsa_rootca.cer --ca-certificate=./OEM-KEYS/qpsa_attestca.cer --ca-key=./OEM-KEYS/qpsa_attestca.key --oem-id=0x1 --oem-product-id=0xabcd --outfile sec.elf
Note The SecTools guides are available to licensed users with authorized access. Important The OEM_enable_bootup_from_a_b_partition configuration is optional and located in trustzone_images/ssg/securemsm/trustzone/qsee/mink/oem/config/<chipset>/oem_config.xml. Its default value is 0. When set to 1 and devcfg recompiled, it enables rollback safety. After the boot confirmation using SMC from UEFI or client applications, it allows TrustZone to update image rollback versions.

​
Use unified image encryption

Unified image encryption (UIE) is a standardized image‑encryption scheme. It uses a hierarchical L1-L2-L3 AES key ladder, L1 is the root key which is fused in Hardware. L2 is the next level key wrapped with the L1 key and L3 is the key used to encrypt the image. It’s wrapped with the L2 key. For command-line usage related to UIE encryption, see SecTools V2: Secure Image User Guide. UIE encryption isn’t supported for IQ-9075/IQ-9100 and IQ-8275/IQ-8300.
Note The SecTools guides are available to licensed users with authorized access.

​
Generate your own key for encryption

  1. The user UIE keys are the standard AES 128 keys and can be generated using the OpenSSL tool.
    Use the command: 
    openssl enc -aes-128-cbc -k <secret> -P -md sha1
    Where:
    • openssl enc: Invokes the OpenSSL encryption tool.
    • -aes-128-cbc: Specifies the encryption algorithm — AES with a 128-bit key in the cipher block chaining (CBC) mode.
    • -k secret: Provides the password (secret) from which the key and initialization vector (IV) are derived.
    • -P: Prints the derived key and IV instead of performing an encryption or decryption.
    • -md sha1: Specifies the message digest algorithm (sha1) used in the key derivation function (KDF).
    For example: 
    openssl enc -aes-128-cbc -k "secret_passphrase" -P -md sha1
    • salt=E2A1F3C4D5B6A798
    • key=5F4DCC3B5AA765D61D8327DEB882CF99
    • iv =AABBCCDDEEFF00112233445566778899
  2. Copy the key to a file to make your key.
    echo -n "5F4DCC3B5AA765D61D8327DEB882CF99"  | xxd -r -p > l1_key.key

​
Generate a UIE sec.elf file

  1. Use the command to generate a UIE sec.elf file. 
    ./sectools fuse-blower --security-profile <chipset>_security_profile.xml --outfile uie_sec.elf --fuse-image-encryption-enable --generate --sign --signing-mode TEST  --fuse-oem-image-encryption-key=0x5F4DCC3B5AA765D61D8327DEB882CF99 --fuse-oem-image-encryption-key-fec-enable
  2. Update the security profile XML appropriate to the chipset.
  3. Use the signing mode as LOCAL or PLUGIN according to the requirement.
  4. Update the encryption key according to your key.
Once the UIE sec.elf file is generated, you can flash it onto the non-secure device. After flashing the UIE sec.elf, you should then flash the secure boot enablement sec.elf along with the other fuses.

​
Encrypt the binaries

To encrypt the binaries with the test keys, use the following arguments along with the signing command. 
--encrypt  --encryption-mode TEST
To encrypt the binaries with the local keys, use the following arguments along with the signing command. 
--encrypt --encryption-mode LOCAL --l1-key l1_key.key

​
Flash the images

Flashing images involves writing an entire image, including partitions, file systems, and data, onto a storage device. This process helps keep the functionality, security, and performance of the device. Follow these steps to flash the images:
  1. See Set QFPROM fuses for the list of fuses to configure.
  2. Replace all binaries with the signed non-Linux binaries generated in  Sign the images, including prog_firehose_ddr.elf. To replace the PIL images, replace the existing PIL images with their corresponding signed versions generated earlier.
    • Extract the <chipset_name.LE.x.x>/common/build/ufs/bin/<chipset_name>_fw.zip file.
    • Replace the PIL split binaries and the .mdt files generated in the signed output into the extracted directory <chipset_name.LE.x.x>/common/build/ufs/bin/<chipset_name>_fw/lib/firmware/qcom/<chipset_name>.
    • Zip the <chipset_name.LE.x.x>/common/build/ufs/bin/<chipset_name>_fw directory with <chipset_name>_fw.zip name.
    • Recompile the Yocto build.
  3. To flash all the signed binaries to the device, see Qualcomm Linux Build Guide.
  4. After generating the signed images and sec.elf, enable secure boot:
    1. Flash the signed images first without sec.elf and ensure that the device boots successfully.
    2. Flash sec.elf by updating the correct rawprogramX.xml file.
      Flash sec.elf by updating the correct rawprogramX.xml file. Find the rawprogramX.xml file with label=“secdata” entry and update the filename in that entry with sec.elf. For example, in QCM6490: <program start_sector="315239" size_in_KB="28.0" physical_partition_number="4" partofsingleimage="false" file_sector_offset="0" num_partition_sectors="7" readbackverify="false" filename="sec.elf" sparse="false" start_byte_hex="0x4cf67000" SECTOR_SIZE_IN_BYTES="4096" label="secdata"/>
    3. Flash the signed images and sec.elf using the flash procedure from Qualcomm Linux Build Guide.
    4. Flash the image using PCAT.
    5. Verify that the secure boot is enabled using Bring up → Verified secure boot. Important With the secure boot enabled, the device expects images to be flashed using a secure programming method called validated image programming (VIP). To proceed, see Perform VIP flashing

​
Next steps