# 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.
## 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**
Note
Secure communications and cryptography are facilitated by the OpenSSL toolkit, while keys and signatures for UEFI secure boot are managed by efitool.
## Install OpenSSL and efitools
1. Install [OpenSSL 0.9.80 June 2010 (or later version)](https://openssl-library.org/source/) on the Linux host computer.
2. Install the [efitools](https://pkgs.org/download/efitools) using the following:
>
>
> - 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
## 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 provisions them in the RPMB or UEFI variable store 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, uki.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.efior UKI.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 wait time in systemd-boot:
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 2` 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. Securely place the signed images and keys in the EFI partition on target.
>
>
> Bring the device into the Fastboot mode and flash the latest `efi.bin` file with the fastboot command:
>
>
>
> >
> >
> > fastboot flash efi
> >
> > fastboot flash dtb_a
> > Copy to clipboard
For more information, see [quic/host-signing-tool](https://github.com/quic/host-signing-tool).
## Enable UEFI secure boot from systemd-boot menu
The EFI binary is composed of signed images and secure boot keys, which are generated and then flashed into the system. For more details, see [Sign images and copy (.auth) key/signed files to EFI partition](https://docs.qualcomm.com/doc/80-70022-11/topic/enable-uefi-secure-boot.html#section-sign-images-copy-auth-key-label).
When the UEFI is loaded and run during the next bootup, the systemd-boot manager displays the **EnrollSecure Boot keys: authkeys** and **Ubuntu1 8.04.6 LTS** menu options on the screen.
Note
These options are displayed when a timeout is configured. For more information, see `loader.conf` settings in [Sign images and copy (.auth) key/signed files to EFI partition](https://docs.qualcomm.com/doc/80-70022-11/topic/enable-uefi-secure-boot.html#section-sign-images-copy-auth-key-label).
**Figure : Systemd-boot menu options**
You can use the volume **+/-** buttons to navigate and select the appropriate option to enroll the keys.
When the key is successfully enrolled, UEFI automatically switches from **SetupMode** to **UserMode**. The logs for the UEFI secure boot enablement are listed in the serial logs when the systemd-boot triggers a system reset to apply the changes.
By default, UEFI starts in **UserMode**, and the UEFI secure boot is initialized during the next boot cycle. The logs for the UEFI secure boot enablement are listed in the serial logs when thesystemd-boot transfers control to the `KERNEL EFI STUB`.
**Figure : UEFI secure boot enablement information from serial log**
The option to enroll with systemd-boot is only available once. This release doesn’t support the reprovisioning and updating of UEFI secure boot keys.
## 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