# Enable UEFI secure boot
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](https://docs.qualcomm.com/doc/80-70030-11/topic/features.html#section-secure-boot-features) and [UEFI secure boot](https://docs.qualcomm.com/doc/80-70030-11/topic/features.html#section-uefi-secure-boot-features) 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.8o.tar.gz June 2010 (or later version)](https://openssl-library.org/source/) on the Linux host computer.
2. Install the following [efitools](https://pkgs.org/download/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](https://docs.qualcomm.com/doc/80-70030-11/topic/features.html#section-rpmb-features).
## Configure 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**
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
Copy to clipboard
### 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
Copy to clipboard
2. Convert the `.crt` file into the `.cer` file:
openssl x509 -outform der -in PK.crt -out PK.cer
Copy to clipboard
3. Convert the `.crt` file into the `.esl` file:
cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl
Copy to clipboard
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
Copy to clipboard
### 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
Copy to clipboard
2. Convert the `.crt` file into the `.cer` file:
openssl x509 -outform der -in KEK.crt -out KEK.cer
Copy to clipboard
3. Convert the `.crt` file into the `.esl` file:
cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl
Copy to clipboard
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
Copy to clipboard
### 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
Copy to clipboard
2. Convert the `.crt` file into the `.cer` file:
openssl x509 -outform der -in db.crt -out db.cer
Copy to clipboard
3. Convert the `.crt` file into the `.esl` file:
cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl
Copy to clipboard
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
Copy to clipboard
## 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 `vmlinuz.x.x.xx` file (Linux) image is placed in the `efimountedbin/ostree/poky-xxx/vmlinuz-x.x.xx` 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` | `/ostree` |
> | --- | --- | --- |
> | `/Boot/bootaa64.efi` | `loader.conf` | `poky-xxx/vmlinuz-x.x.xx` |
> | | `/keys/authkeys/db.auth`
`/keys/authkeys/PK.auth` |
### 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 `` directory and create an `efimountedbin` directory within the `` 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
Copy to clipboard
cd efimountedbin
Copy to clipboard
5. Mount the `dtb.bin` file:
sudo mount dtb.bin dtbmountedbin
Copy to clipboard
cd dtbmountedbin
Copy to clipboard
6. Create an authkeys directory within the `/efimountedbin/loader/keys` directory to enroll keys.
7. Select and copy the `.auth` files (`PK.auth`, `KEK.auth`, and `db.auth`) to the authkeys directory.
sudo cp /efimountedbin/loader/keys/authkeys/
Copy to clipboard
8. Create an `authkeys` directory within the `/dtbmountedbin/loader/keys directory` to enroll keys.
9. Select and copy the `.auth files` (PK.auth, KEK.auth, and dB.auth) to the authkeys directory in `dtbmountedbin`.
sudo cp /dtbmountedbin/loader/keys/authkeys/
Copy to clipboard
10. Sign the `bootaa64.efi and dtb`, `vmlinuz-x.x.xx`, and `combined-dtb.dtb` image files with the keys and copy to the respective directories in the `efimountedbin`
directory.
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` directory `/EFI/BOOT` and the `vmlinuz-x.x.xx` file from the `/ostree/poky-xxx/vmlinuz.x.x.xx ` directory to the :file:`images` directory on your Linux machine.
2. Sign the images:
>
>
> cd /images
> Copy to clipboard
>
>
> sudo sbsign --key /keys/db.key --cert /keys/db.crt bootaa64.efi --output /bootaa64.efi
> Copy to clipboard
>
>
> sudo sbsign --key /keys/db.key --cert /keys/db.crt vmlinuz.x.x.xx --output /vmlinuz.x.x.xx
> Copy to clipboard
2. 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 –out < Output .dtb.sig file > -outform DER
> Copy to clipboard
2. To sign the image, run the following command:
>
>
> cd /images
> Copy to clipboard
>
>
> sudo openssl cms -sign -inkey /keys/db.key -signer /keys/db.crt -binary -in combined-dtb.dtb --out combined-dtb.sig -outform DER
> Copy to clipboard
11. Copy the signed `combined-dtb.sig`, `vmlinuz.x.x.xx`, and `bootaa64.efi` images back to their respective directories `(dtbmountedbin/, efimountedbin/ostree/poky-xxx/, and efimountedbin/EFI/BOOT/)`.
12. 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
> Copy to clipboard
2. Add the line `timeout 10` to set the boot menu timeout and save the file.
13. To unmount the EFI binary to retrieve the latest `efi.bin` file, run the command:
>
>
> sudo umount efimountedbin
> Copy to clipboard
14. To unmount the DTB binary to retrieve the latest `dtb.bin` file, run the command:
>
>
> sudo umount dtbmountedbin
> Copy to clipboard
15. 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
>
> fastboot flash dtb_a
> Copy to clipboard
## 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](https://docs.qualcomm.com/doc/80-70030-11/topic/enable-uefi-secure-boot.html#section-sign-images-copy-auth-key-label).
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.
The following steps enable 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.
> Copy to clipboard
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!
> Copy to clipboard
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.
>
>
> 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...
> Copy to clipboard
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