Skip to main content
UEFI secure boot enhances the security and reliability of the system by ensuring that only the verified and trusted software loads during startup. Secure boot and UEFI secure boot are distinct security features and cover different images for authentication. UEFI secure Boot can be enabled either on a secure boot device or, for testing purposes, on a non-secure boot device.

​
Prerequisites

​
Host requirements

  1. Install OpenSSL 0.9.80 June 2010 (or later version) on the Linux host computer.
  2. Install the following efitools:
    • cert-to-efi-sig-list: converts OpenSSL certificates to EFI signature lists
    • sign-efi-sig-list: signs the EFI signature list
    • hash-efi-sig-list: creates a hash signature list entry from a binary

​
Provision replay protected memory block on device

Replay protected memory block (RPMB) provisioning is mandatory for UEFI secure boot enablement. For more information, see RPMB.

​
Configure an UEFI secure boot to generate keys and certificates

You can setup an initial UEFI secure boot configuration and convert the keys and certificates into a format that UEFI can understand. See the workflow to understand the off-target preparation and the on-device execution. Figure : UEFI secure boot workflow UEFI secure boot workflow Note Secure communications and cryptography are facilitated by the OpenSSL toolkit, while keys and signatures for UEFI secure boot are managed by efitool.

​
Generate key and certificate

To enable UEFI secure boot, generate a pair of keys and certificates for signing and authentication. The key generation supports the following algorithms:
  • RSA 2048/4096 with SHA-256/SHA384 hash algorithm
  • ECDSA secp256r1/secp384r1
The following procedures provide instructions to generate keys and certificates with RSA 2048 and SHA-256 as an example. Note
  • Create a directory and run the commands in the same location to perform these steps on a Linux machine.
  • For ECC, replace rsa:2048 with ec:secp384r1 or ec:secp256r1. For SHA384, replace -sha256 with -sha384 in the following commands.

​
Generate UID

You can generate a GUID and create three new keys with self-signed certificates in CRT/PEM format and keys in .key format: GUID uses uuidgen to generate the signature owner GUID: 
uuidgen --random > GUID.txt

​
Create PK key

  1. Create a PK key pair (RSA-2048) and certificate: 
    openssl req -new -x509 -newkey rsa:2048 -subj "/CN=Custom PK/" -keyout PK.key -out PK.crt -days 3650 -nodes -sha256
  2. Convert the .crt file into the .cer file: 
    openssl x509 -outform der -in PK.crt -out PK.cer
  3. Convert the .crt file into the .esl file: 
    cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl
  4. Sign and generate the .auth file with the .crt, .esl, and .key files: 
    sign-efi-sig-list -k PK.key -c PK.crt PK PK.esl PK.auth

​
Create KEK key

  1. Create a KEK key pair (RSA-2048) and certificate: 
    openssl req -new -x509 -newkey rsa:2048 -subj "/CN=Custom KEK/" -keyout KEK.key -out KEK.crt -days 3650 -nodes -sha256
  2. Convert the .crt file into the .cer file: 
    openssl x509 -outform der -in KEK.crt -out KEK.cer
  3. Convert the .crt file into the .esl file: 
    cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl
  4. Sign and generate the .auth file with the .crt, .esl, and .key files: 
    sign-efi-sig-list -k PK.key -c PK.crt KEK KEK.esl KEK.auth

​
Create dB key

  1. Create a dB key pair (RSA-2048) and certificate: 
    openssl req -new -x509 -newkey rsa:2048 -subj "/CN=Custom DB Signing Key 1/" -keyout db.key -out db.crt -days 3650 -nodes -sha256
  2. Convert the .crt file into the .cer file: 
    openssl x509 -outform der -in db.crt -out db.cer
  3. Convert the .crt file into the .esl file: 
    cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl
  4. Sign and generate the .auth file with the .crt, .esl, and .key files: 
    sign-efi-sig-list -k KEK.key -c KEK.crt db db.esl db.auth

​
Sign images and copy (.auth) key/signed files to EFI partition

The EFI system partition consists of EFI, loader, and ostree with information relevant to EFI when using systemd-boot. The DTB partition consists of dtb directories. The EFI system partition holds essential files for booting the system and managing updates, while the DTB partition contains hardware configuration information. This section provides instructions to:
  • Sign various images.
  • Copy (.auth) key and signed files to EFI partition and DTB partition directories.
  • Signed and executable images such as the bootaa64.efi file (systemd-boot) are placed in the efimountedbin/EFI/BOOT/ directory and the linux-<target-name>.efi file (Linux) image is placed in the efimountedbin/EFI/Linux directory.
The systemd-boot validates the signed images and is also used to enroll the following:
  • UEFI secure boot keys are placed in a specific directory in /keys for key enrollment. The systemd-boot uses these keys and stores them in the RPMB during UEFI boot time services.
  • You can configure the wait time (in seconds) in the systemd-boot loader configuration. Kernel loading is delayed during the wait time, allowing you to review and select available options in the systemd-boot menu.
  • Device tree files are stored in the dtbmountedbin/dtb directory. These files are used by UEFI during runtime, and the device tree files are initialized. While signing, .sig files are created and placed in the same directory as these files are non-PE images.
    Table : EFI system partition (efi.bin)
    /EFI/Loader
    /Boot/bootaa64.efiloader.conf
    /Linux/linux-<target-name>.efi/keys/authkeys/db.auth /keys/authkeys/KEK.auth /keys/authkeys/PK.auth
    Table : DTB partition (dtb.bin)
    ------
    qclinux_fit.img (or combined-dtb.dtb)qclinux_fit.sig (or combined-dtb.sig)

​
Place signed images and keys in EFI partition

Follow these steps to place the signed images and keys in an EFI partition on a Linux host machine.
  1. Locate the efi.bin and dtb.bin file paths in the contents.xml, file to obtain the efi.bin and dtb.bin` files from the meta.
  2. Mount the efi.bin file into the <workspace> directory and create an efimountedbin directory within the <workspace> directory.
  3. Mount the dtb.bin file into the <workspace> directory and create a dtbmountedbin directory within the <workspace> directory.
  4. Mount the efi.bin file: 
    sudo mount efi.bin efimountedbin

    cd efimountedbin
  5. Mount the dtb.bin file: 
    sudo mount dtb.bin dtbmountedbin

    cd dtbmountedbin
  6. Create the loader/keys/authkeys directory chain in <workspace>/efimountedbin/ to enroll keys.
  7. Select and copy the .auth files (PK.auth, KEK.auth, and db.auth) to the authkeys directory in efimountedbin. 
    sudo cp <selected algo PK/KEK/DB auth files from the files location> <workspace>/efimountedbin/loader/keys/authkeys/
  8. Sign the bootaa64.efi, linux-<target-name>.efi, and qclinux_fit.img (or combined-dtb.dtb) binary files with the keys and copy to the respective directories in the efimountedbin and dtbmountedbin directories.
    1. Sign efi images:
      The sbsign tool is designed for signing EFI boot images, such as bootaa64.efi that follow EFI specifications. This tool, which is used for UEFI secure boot signing is available for download and use on Linux systems. It’s important to note that sbsign can only sign PE images with a .efi extension.
      1. Copy the bootaa64.efi file from the /efimountedbin/EFI/BOOT directory and the linux-<target-name>.efi file from the efimountedbin/Linux/ directory to the <workspace>/images directory on your Linux machine.
      2. Sign the images: 
      cd <workspace>/images

      sudo sbsign --key <workspace>/keys/db.key --cert <workspace>/keys/db.crt bootaa64.efi --output <workspace>/bootaa64.efi

      sudo sbsign -key <workspace>/keys/db.key --cert <workspace>/keys/db.crt linux<target-name>.efi -output <workspace>/linux<target-name>.efi
    1. Sign the dtb image: All images authenticated by UEFI secure boot are regular APIs and typically in the PE format. The signature header and size are appended to the existing PE header, and the signature is appended at the end of the signed file. However, when images in non-PE formats require UEFI secure boot authentication, the absence of the PE header and its magic number to recognize the image format fail. As a result, it’s not possible to use standard tools and paths for image verification. Currently, among the list of images that UEFI secure boot verifies, only the dtb files are in non-PE format images. As an alternative to the sbsign tool, you can use the OpenSSL cms command to generate signature files for signing images in non-PE format. Follow these steps for signing non-EFI images:
      1. To sign the dtb file and signature file, run the following command:
      openssl cms -sign -inkey <.key file> -signer <.crt file> -binary -in <input dtb file>-out <output .dtb.sig file> -outform DER
      1. To sign the image, run the following command:
      cd <workspace>/images

      sudo openssl cms -sign -inkey <workspace>/keys/db.key -signer <workspace>/keys/db.crt -binary -in qclinux_fit.img <or combined-dtb.dtb> --out qclinux_fit.sig <or combined-dtb.sig> -outform DER
  9. Copy the signed qclinux_fit.img, linux-<target-name>.efi, and bootaa64.efi images back to their respective directories (dtbmountedbin/, efimountedbin/Linux/, and efimountedbin/EFI/BOOT/).
  10. Configure the timeout duration of systemd-boot manager to display menu:
    1. Open and edit the loader.conf file at /loader/loader.conf with sudo access:
    sudo vi loader.conf
    1. Add the line timeout 10 to set the boot menu timeout and save the file.
  11. To unmount the EFI binary to retrieve the latest efi.bin file, run the command:
sudo umount efimountedbin
  1. To unmount the DTB binary to retrieve the latest dtb.bin file, run the command:
sudo umount dtbmountedbin
  1. To flash signed images and keys on the target, bring the device into the Fastboot mode and using following commands flash updated efi.bin and dtb.bin images:
fastboot flash efi <efi binary location>

fastboot flash dtb_a <dtb binary location>

fastboot reboot

​
Enable UEFI secure boot from systemd-boot menu

Ensure that the EFI signed images and the secure boot keys are first generated and then flashed on the target, along with the systemd-boot manager timeout configuration. For more details, see Sign images and copy (.auth) key/signed files to EFI partition. Note The key enrollment using systemd-boot manager to store keys into RPMB is a one-time operation. After successful key enrollment, the reprovisioning and updating of UEFI secure boot keys isn’t possible. Following steps enables the UEFI secure boot on the device.
  1. After the UEFI is loaded and run during the next bootup, the systemd-boot manager displays the following interactive menu on the serial log. 
    Qualcomm Linux 1.5-ver.1.1 (ostree:0) Enroll Secure Boot keys: authkeys
Boot in 10 s. ?????????????????????????????????????????????????
Boot in 9 s. ?????????????????????????????????????????????????
Boot in 8 s.
  2. Use vol- key to stop the timeout, which displays Enroll Secure Boot keys: authkeys.
  3. Use power key to start enrollment. This is followed by a timeout with option to abort this enrollment operation, in this timeout duration don’t use any key. After this timeout is completed, the key enrollment operation is executed. A successful key enrollment is shown in the following log. 
    Qualcomm Linux 1.5-ver.1.1 (ostree:0) Enroll Secure Boot keys: authkeys Enrolling secure boot keys from directory: \loader\keys\authkeys
Warning: Enrolling custom Secure Boot keys might soft-brick your machine!
Enrolling in 15 s, press any key to abort.
...
Enrolling in  0 s, press any key to abort.
Custom Secure Boot keys successfully enrolled, rebooting the system now!
  4. After the key is successfully enrolled, UEFI automatically switches from SetupMode to UserMode. Then systemd-boot triggers a device reboot.
  5. On next device bootup, UEFI starts in UserMode and the UEFI secure boot is enabled. A successful enablement of UEFI secure boot is shown in the following serial log. 
    OS DTB Authentication Success status = 0
Authenticate OS DTB Success! Status = Success
And if EFI Stub level logging is enabled through kernel config then,
EFI stub: Booting Linux Kernel...
EFI stub: Loaded initrd from LINUX_EFI_INITRD_MEDIA_GUID device path
EFI stub: UEFI Secure Boot is enabled.
EFI stub: Using DTB from configuration table
EFI stub: Exiting boot services...
  6. Once the UEFI secure boot is successfully enabled, revert the systemd-boot manager timeout configuration.

​
Hash unsigned images and update DB for image authentication

UEFI secure boot allows image authentication. This authentication is achieved through the hash of images stored in the signature database (dB), even if the images aren’t signed or the certificates in the images aren’t present in the dB. This process is reserved for content that can’t be signed or altered from its vendor-provided state. If the image hash is available in the database deny (dBX) list, the trust of signed binaries can be removed without having to revoke the corresponding certificates or keys. This is useful, for example, when dealing with an earlier signed boot loader that’s vulnerable to recent exploits. It’s redundant to apply a signature and create a dB hash for the same binary. Follow these steps if the image composition doesn’t require any changes, meaning no new keys and certificates are being added or modified in the image, and no UEFI secure boot authentication is needed for the existing images. You can calculate the hash of images and generate an allowed signature dB file.

​
Generate db.auth file for unsigned images

  1. Generate a hash of all images to be verified and convert the hash into an .esl file: 
    hash-to-efi-sig-list <list of efis to be hashed>  <output file name with .esl extension>
  2. Sign the .esl hash file with the dB key: 
    sign-efi-sig-list -k < .key file location > -c < .crt file location > <secure variable name> <Above generated .esl file> <o/p .auth file>
  3. Copy the generated db.auth file into the EFI binary and provision the keys into the device.
For example, on a Linux host machine:
  1. Mount the efi.bin file to the <workspace> directory and create an efimountedbin folder in the <workspace> directory.
  2. Create a testkeys folder in the <workspace> directory on the Linux machine and copy the pre-existing keys to it.
  3. Sign the images: 
    hash-to-efi-sig-list <workspace>/efimountedbin/EFI/BOOT/bootaa64.efi mergedhash.esl

    sign-efi-sig-list -k keys db.key -c db.crt db mergedhash.esl db.auth
  4. Copy the db.auth file to the qckeys folder at <workspace>/efimountedbin/loader/keys/qckeys.
  5. Follow the dtb signing steps and sign the dtb images to generate a new efi.bin file. For more information, see Sign images and copy (.auth) key/signed files to EFI partition.
  6. For a Linux host machine on the target:
    1. Erase any existing UEFI secure boot keys and flash the EFI binary with fastboot.
    2. Provision keys with systemd-boot. For more information, see Enable UEFI secure boot from systemd-boot menu. Note All unsigned files are signed with other keys and authenticated with UEFI using this method.

​
Next steps