Skip to content

configure-secure-boot.md

Latest commit

 

History

History
189 lines (132 loc) · 4.89 KB

configure-secure-boot.md

File metadata and controls

189 lines (132 loc) · 4.89 KB

Configure Secure Boot

This guide walks you through setting up Secure Boot for your operating system images using the OS Image Composer tool. Follow each step carefully.

Prerequisites

  • Linux environment with OpenSSL installed
  • QEMU with OVMF UEFI firmware
  • OS Image Composer tool configured

Step 1: Generate Secure Boot Keys

Create a directory for your keys and generate the required certificates:

# Create a directory for secure boot keys
mkdir -p /data/secureboot/keys
cd /data/secureboot/keys

# Generate private key and certificate using RSA 3072-bit with SHA-384
openssl req -new -x509 -newkey rsa:3072 -sha384 -keyout DB.key -out DB.crt -days 3650 -nodes -subj "/CN=ICT Secure Boot Key/"

# Convert certificate to DER format (required by UEFI)
openssl x509 -outform DER -in DB.crt -out DB.cer

NOTE: The signing keypair strength should align with the crypto implementation supported by the UEFI Secure boot implementation on a specific system. The recommendation is to test the support for RSA3072SHA384 before moving to RSA2048SHA256.

What you'll have:

  • DB.key - Private key (keep secure)
  • DB.crt - Certificate in PEM format
  • DB.cer - Certificate in DER format (for UEFI)

Step 2: Configure Your Template

Edit your OS Image Composer template YAML file to include the Secure Boot configuration:

# Add this section to your template
immutability:
  enabled: true
  secureBootDBKey: "/data/secureboot/keys/DB.key"
  secureBootDBCrt: "/data/secureboot/keys/DB.crt"
  secureBootDBCer: "/data/secureboot/keys/DB.cer"

Important: Use absolute paths to your key files.

Step 3: Build Your OS Image

Run ICT to build your image as usual.

Step 4: Verify Build Output

After a successful build, check the output directory, for example:

ls ./tmp/os-image-composer/wind-river-elxr-elxr12-x86_64/imagebuild/Default_Raw/ -la

Expected output:

  • minimal-os-image-elxr.raw - Your bootable OS image
  • DB.cer - Secure Boot certificate (copied during build)

Step 5: Prepare Image for Testing

Copy the certificate to the EFI partition for easier key enrollment:

# Mount the raw image
sudo losetup -Pf minimal-os-image-elxr.raw

# Find the loop device (usually /dev/loop0)
LOOP_DEVICE=$(losetup -l | grep minimal-os-image-elxr.raw | awk '{print $1}')
echo "Using loop device: $LOOP_DEVICE"

# Check partitions
lsblk $LOOP_DEVICE

# Mount EFI partition (usually partition 1)
sudo mkdir -p /mnt/efi
sudo mount ${LOOP_DEVICE}p1 /mnt/efi

# Create keys directory and copy certificate
sudo mkdir -p /mnt/efi/EFI/keys
sudo cp DB.cer /mnt/efi/EFI/keys/

# Cleanup
sudo umount /mnt/efi
sudo losetup -d $LOOP_DEVICE

Step 6: Boot Image in QEMU

Launch QEMU with UEFI firmware:

sudo qemu-system-x86_64 \
  -m 2048 \
  -enable-kvm \
  -cpu host \
  -bios /usr/share/OVMF/OVMF_CODE.fd \
  -device virtio-scsi-pci \
  -drive if=none,id=drive0,file=minimal-os-image-elxr.raw,format=raw \
  -device scsi-hd,drive=drive0 \
  -nographic \
  -serial mon:stdio \
  -boot menu=on

Tip: Press Esc repeatedly as soon as QEMU starts to enter UEFI setup.

Step 7: Enroll Secure Boot Keys

Once you're in the UEFI setup menu, do the following.

Note: Menu names vary by firmware. Look for similar options if the exact names differ.

Navigate to Secure Boot

  1. Use arrow keys to find "Device Manager" or "Secure Boot Configuration"
  2. Look for "Secure Boot" or "Security" menu

Enable Custom Mode

  1. Find "Secure Boot Mode"
  2. Change from "Standard" to "Custom"
  3. This allows manual key management

Enroll Your Key

  1. Navigate to "Custom Secure Boot Options"
  2. Select "DB Options" (Database Options)
  3. Choose "Enroll Signature" or "Enroll DB"
  4. Navigate to: fs0:\EFI\keys\DB.cer
  5. Select the file and confirm enrollment

Save and Exit

  1. Press F10 to save changes
  2. Select "Reset" or "Exit"
  3. System will reboot

Step 8: Verify Secure Boot

After the system boots completely, verify that Secure Boot is working:

# Check if Secure Boot is enabled
sudo dmesg | grep -i secure

# Expected output:
# [    0.000000] secureboot: Secure boot enabled
# [    0.716009] integrity: Loaded X.509 cert 'ICT Secure Boot Key: [key-hash]'

Troubleshooting

Common Issues:

  1. Can't find keys in UEFI: Ensure the EFI partition is mounted and files are in /EFI/keys/.
  2. Secure Boot not enabled: Verify you're in "Custom" mode, not "Standard" mode.
  3. Boot fails after key enrollment: Check that your image was built with the same keys.

Recovery:

  • Boot QEMU without Secure Boot: Remove -bios /usr/share/OVMF/OVMF_CODE.fd
  • Reset UEFI settings: In UEFI setup, look for "Reset to defaults."

Summary

You've successfully:

  • ✅ Generated Secure Boot keys
  • ✅ Built an image with Secure Boot enabled
  • ✅ Enrolled keys in UEFI firmware
  • ✅ Verified Secure Boot functionality