==========================================================
Secure Boot Authenticity Verification for CIP Image (RST)
==========================================================

The following steps verify the authenticity of the boot process of a CIP image.

-------------------------
1. Install efitools & Generate Keys
-------------------------

Install ``efitools`` and generate keys using Debian snakeoil certificates:

::

   host$ sudo apt install efitools
   host$ cert-to-efi-sig-list recipes-devtools/secure-boot-secrets/files/bookworm/PkKek-1-snakeoil.pem PK.esl
   host$ sign-efi-sig-list \
         -k recipes-devtools/secure-boot-secrets/files/bookworm/PkKek-1-snakeoil.key \
         -c recipes-devtools/secure-boot-secrets/files/bookworm/PkKek-1-snakeoil.pem \
         PK PK.esl PK.auth

This generates ``PK.esl`` and ``PK.auth`` files.

-------------------------
2. Prepare USB Stick with Keys & KeyTool
-------------------------

Format the USB device and copy the Secure Boot files:

::

   host$ sudo mkfs.vfat /dev/<usb device>
   host$ sudo mount -t vfat /dev/<usb device> /mnt/
   host$ sudo cp /usr/lib/efitools/x86_64-linux-gnu/KeyTool.efi /mnt/
   host$ sudo cp PK.esl PK.auth /mnt/
   host$ sudo umount /mnt

-----------------------------------------
3. Inject Secure Boot Keys into M-COM BIOS
-----------------------------------------

Insert the USB stick into the M-COM device.

Power on and press **F12** to enter *BIOS Setup*.

**Under Security tab:**

- Select **Secure Boot**  
- Disable Secure Boot if enabled  
- The *System Mode* will be **User**

Perform Secure Boot reset:

- Select **Reset To Setup Mode**  
- Confirm deletion of all Secure Boot keys  
- System Mode should change to **Setup**

**Under Save & Exit tab:**

- Go to **Boot Override**  
- Select **UEFI: Built-in EFI shell**  
- In the EFI shell, enter the USB device: ``fs0:``  
- Run ``KeyTool.efi``  
- Follow **Step 4** under *Add Keys to OVMF* from documentation\*  
- Use:  
  - ``PK.esl`` (instead of ``demoDB.esl`` and ``demoKEK.esl``)  
  - ``PK.auth`` (instead of ``demoPK.auth``)  
- Additionally inject ``PK.esl`` into the **Forbidden Signature Database (dbx)**  
- Exit KeyTool and the EFI shell  
- System boots the existing image on eMMC  
- Reboot and press **F12** to enter BIOS setup again

**Enable Secure Boot:**

- Under Security → Secure Boot → Enable Secure Boot  
- Under Save & Exit → Save Changes & Exit

-----------------------------------------
4. Expected Boot Failure — Verification
-----------------------------------------

When the system boots, it should fail with:

::

   "Invalid signature detected, check secureboot policy in setup"

Selecting **OK** returns to BIOS.

This confirms that firmware signed with a **forbidden dbx key** will be denied boot.

-----------------------------------------
Reverting Changes — Restore Normal Boot
-----------------------------------------

To remove the dbx key and restore normal operation:

1. Go to **Security → Secure Boot → Key Management**
2. Navigate to **Forbidden Signatures (dbx)**
3. Select **Delete**
4. When prompted:

   - *"Press Yes to delete the variable and No to delete only a certificate"*  
     → Select **No**

5. A list of certificates is displayed  
   → Select the injected certificate  
   → Confirm deletion
6. Save & Exit BIOS
7. Confirm that the device boots successfully with Secure Boot enabled.

-----------------------------------------
Footnotes
-----------------------------------------

\* The referenced "Add Keys to OVMF" Step 4 is part of standard efitools key enrollment instructions.