photonos-secureboot-iso

name: photonos-secureboot-iso description: | Create UEFI Secure Boot enabled Photon OS ISOs for physical hardware. Handles MOK enrollment, custom GRUB stub, RPM signing, and kickstart installation. Use when building bootable ISOs for laptops/servers with Secure Boot enabled.

PhotonOS HABv4 Secure Boot ISO Creation Skill

Overview

This skill covers creating Secure Boot enabled ISOs for Photon OS that work on consumer laptops and servers with UEFI Secure Boot enabled. The tool creates modified ISOs using:

• SUSE shim (Microsoft-signed, SBAT compliant)
• Custom GRUB stub (MOK-signed, without shim_lock)
• MOK-signed kernel and packages
• Kickstart-based installation for reliable package selection

The Problem We Solve

Original Photon OS ISOs fail on Secure Boot enabled hardware because:

1. VMware's shim has shim_lock that rejects custom/unsigned kernels
2. The kernel isn't signed with a key in MokList
3. Installed packages use VMware's signing, not user-controlled keys

Our solution:

1. Replace VMware shim with Microsoft-signed SUSE shim
2. Build custom GRUB stub without shim_lock, sign with MOK
3. Sign kernel with MOK
4. Create -mok variant RPM packages for installed system

Quick Reference

Build Commands

# Build Secure Boot ISO (simplest - does everything)
./PhotonOS-HABv4Emulation-ISOCreator -b

# Build for specific release
./PhotonOS-HABv4Emulation-ISOCreator --release 6.0 --build-iso

# Build with RPM signing (compliance: NIST 800-53, FedRAMP, EU CRA)
./PhotonOS-HABv4Emulation-ISOCreator --build-iso --rpm-signing

# Build with eFuse USB verification
./PhotonOS-HABv4Emulation-ISOCreator --build-iso --efuse-usb --create-efuse-usb=/dev/sdX -y

# Diagnose existing ISO
./PhotonOS-HABv4Emulation-ISOCreator -D /path/to/iso

Command Line Options

Architecture

Boot Chain (ISO Boot)

UEFI Firmware (Microsoft UEFI CA in db)
    ↓ verifies Microsoft signature
BOOTX64.EFI (SUSE shim, SBAT=shim,4)
    ↓ verifies against MokList
grub.efi (Custom GRUB stub, MOK-signed, NO shim_lock)
    ↓ loads grub.cfg with themed menu (5 sec timeout)
    │
    └─→ "Install" → launches interactive installer
        │
        ↓ Package Selection Screen (modified build_install_options_all.json)
        │
        ├─→ "1. Photon MOK Secure Boot" → packages_mok.json
        │   → Installs: linux-mok, grub2-efi-image-mok, shim-signed-mok
        │
        ├─→ "2. Photon Minimal" → packages_minimal.json (original)
        │   → Installs: linux, grub2-efi-image, shim-signed
        │
        └─→ "3-5. Developer/OSTree/RT" → respective package files

Boot Chain (Installed System - MOK Path)

UEFI Firmware → shim-signed-mok (SUSE shim + MokManager)
             → grub2-efi-image-mok (Custom GRUB stub, MOK-signed)
             → linux-mok (vmlinuz, MOK-signed)
             ✓ Works on physical hardware with Secure Boot

Why Custom GRUB Stub Without shim_lock

VMware's GRUB includes the shim_lock verifier module which calls shim's Verify() for kernel loading. While MOK-signed kernels should be accepted (certificate in MokList), we build a custom stub without shim_lock to ensure compatibility and provide predictable behavior.

The custom stub:

1. Is verified by shim via MOK signature (chain maintained)
2. Excludes shim_lock (no unpredictable kernel verification)
3. Contains SBAT metadata (passes shim policy check)
4. Includes modules for theming: probe, gfxmenu, png, jpeg, tga

RPM Secure Boot Patcher

The tool includes an integrated RPM patcher that creates MOK-signed variant packages:

Package Discovery (Version-Agnostic)

The patcher discovers packages by file paths, not version numbers:

• grub2-efi-image: provides /boot/efi/EFI/BOOT/grubx64.efi
• linux: provides /boot/vmlinuz-*
• shim-signed: provides /boot/efi/EFI/BOOT/bootx64.efi

SPEC File Generation

Generated specs include:

• Proper Provides: (same capability as original)
• Conflicts: (prevents installing both)
• MOK-signed binaries
• MokManager in shim-signed-mok

Interactive Installation with MOK Package Option (v1.6.0)

The ISO uses a fully interactive installer with MOK packages added to the package selection menu. This is Option C from the architecture decision record (see ADR-001 in DROID_SKILL_GUIDE.md).

How It Works

1. Single GRUB menu entry: "Install" launches the interactive installer
2. No kickstart files: Full interactive experience (EULA, disk, hostname, password)
3. Modified build_install_options_all.json: Adds "Photon MOK Secure Boot" as first option
4. New packages_mok.json: Contains MOK-signed packages (dynamically generated)

Initrd Modifications

The tool modifies the initrd to:

1. Create packages_mok.json in /installer/ (dynamically generated in v1.9.18+):

{
    "packages": [
        "bash-completion", "bc", "bridge-utils", "...",
        "grub2-efi-image-mok",  // Replaces grub2-efi-image
        "linux-mok",            // Replaces linux/linux-esx
        "shim-signed-mok",      // Replaces shim-signed
        "initramfs", "lvm2", "less", "sudo", "..."
    ]
}

Note: Since v1.9.18, packages_mok.json is dynamically generated:

• The minimal meta-package is expanded to its direct dependencies
• grub2-efi-image is replaced with grub2-efi-image-mok
• This prevents tdnf from selecting both original and MOK packages (which causes Error 1525)

2. Modify build_install_options_all.json to add MOK option first:

{
    "mok": {
        "title": "1. Photon MOK Secure Boot",
        "packagelist_file": "packages_mok.json",
        "visible": true
    },
    "minimal": {
        "title": "2. Photon Minimal",
        ...
    }
}

3. Patch linuxselector.py to recognize linux-mok kernel:

linux_flavors = {"linux-mok":"MOK Secure Boot", "linux":"Generic", ...}

Why Interactive Instead of Kickstart

Previous versions (v1.5.0) used kickstart files with "ui": true. This failed because:

• Photon installer architecture: Interactive UI only runs when NO kickstart is provided
• ui: true misconception: Only controls progress bars, not the configuration wizard
• Missing required fields: Kickstart without disk/hostname caused crashes

The interactive approach (Option C):

• Full user control: EULA, disk selection, partitioning, hostname, password
• Explicit MOK choice: Users see "Photon MOK Secure Boot" in package selection
• Preserves options: All original package options remain available
• Follows installer patterns: Uses official build_install_options_all.json mechanism

Kernel Build Support

The tool automatically builds kernels from Photon OS sources with Secure Boot configuration:

Directory Structure Supported

Auto-detection (v1.9.28+): For release 6.0 and future releases, the tool automatically scans /root/common/SPECS/linux/ for version directories (v6.1, v6.12, etc.) and selects the highest version. This ensures Photon 6.0 uses kernel 6.12.x instead of 6.1.x.

Build Process

1. Auto-detect kernel tarball from SOURCES/
2. Extract to {photon_dir}/kernel-build/linux-{version}/
3. Apply Photon config (config-esx_{arch} preferred for VMs)
4. Configure Secure Boot options:
   • CONFIG_MODULE_SIG=y
   • CONFIG_MODULE_SIG_ALL=y
   • CONFIG_MODULE_SIG_SHA512=y
   • CONFIG_LOCK_DOWN_KERNEL_FORCE_INTEGRITY=y
5. Build kernel and modules
6. Sign kernel with MOK key
7. Output to {keys_dir}/vmlinuz-mok

RPM Signing (Optional)

The --rpm-signing option enables GPG signing for compliance:

Compliance Standards Supported

• NIST SP 800-53: SI-7 (Software Integrity), CM-14 (Signed Components)
• FedRAMP: Requires NIST 800-53 controls
• EU Cyber Resilience Act: Article 10 (Software integrity verification)

Process

1. Generate GPG key pair (RPM-GPG-KEY-habv4)
2. Sign all MOK RPMs with rpmsign
3. Copy public key to ISO and eFuse USB
4. Import key in kickstart postinstall

Verification

rpm -qa gpg-pubkey* --qf '%{NAME}-%{VERSION}-%{RELEASE}\t%{SUMMARY}\n'
rpm -qa *-mok* --qf '%{NAME}\t%{SIGPGP:pgpsig}\n'

Driver Integration (v1.9.5)

The --drivers option allows including additional driver firmware RPMs in the ISO:

Usage

# Use default drivers directory (drivers/RPM/)
./PhotonOS-HABv4Emulation-ISOCreator -b --drivers

# Use custom drivers directory
./PhotonOS-HABv4Emulation-ISOCreator -b --drivers=/path/to/custom/drivers

How It Works

1. Scan: Tool scans drivers directory for .rpm files
2. Detect: RPM names are matched against known driver patterns (iwlwifi, rtw88, brcmfmac, etc.)
3. Configure: Kernel is automatically configured with required modules for detected drivers
4. Build: Kernel is built with driver support enabled
5. Package: Driver RPMs are copied to ISO and added to packages_mok.json
6. Install: When selecting "Photon MOK Secure Boot", drivers are installed automatically

Supported Driver Types

Included Packages (v1.9.12+)

The drivers/RPM/ directory includes:

• wireless-regdb-2024.01.23-1.ph5.noarch.rpm: WiFi regulatory database from kernel.org
• iw-6.9-1.ph5.x86_64.rpm: nl80211 wireless configuration utility from kernel.org
• linux-firmware-iwlwifi-ax211-20260128-1.ph5.noarch.rpm: Intel Wi-Fi 6E AX211 firmware (PCI IDs: 8086:51f0, 8086:51f1)

Note: wireless-regdb and iw are built from upstream sources because they're not available in Photon OS 5.0 repos.

Rebuilding Driver Packages

Spec files and build script are included:

# Rebuild wireless-regdb and iw from upstream sources
./drivers/build-wireless-packages.sh

Adding Custom Drivers

1. Place firmware RPM in drivers/RPM/
2. If driver type is not in supported list, add mapping entry in source code
3. Rebuild ISO with --drivers

eFuse USB Mode

When built with -E, boot requires an eFuse USB dongle (label: EFUSE_SIM):

GRUB Stub
    ↓
Search for USB with LABEL=EFUSE_SIM
    ↓
Check for /efuse_sim/srk_fuse.bin
    ├─→ Valid: Show boot menu
    └─→ Invalid: "BOOT BLOCKED" (only Retry/Reboot)

Hot-plug detection (v1.9.20+): If eFuse USB is plugged in after GRUB starts, selecting "Retry" uses chainloader to reload GRUB and rescan USB devices. This fixes the issue where configfile reload didn't detect newly inserted USB.

USB Contents

USB (FAT32, LABEL=EFUSE_SIM)
└── efuse_sim/
    ├── srk_fuse.bin          # SRK hash (32 bytes)
    ├── sec_config.bin        # Security mode
    └── efuse_config.json     # Configuration

First Boot Procedure

Step 1: Write USB

dd if=photon-5.0-secureboot.iso of=/dev/sdX bs=4M status=progress
sync

Step 2: BIOS Configuration

1. Disable CSM/Legacy boot completely
2. Enable Secure Boot
3. Set USB as first boot device

Step 3: Enroll MOK (First Boot)

1. Blue MokManager screen appears (not laptop's security dialog)
2. Select "Enroll key from disk"
3. Navigate to root /
4. Select ENROLL_THIS_KEY_IN_MOKMANAGER.cer
5. Confirm and select "Reboot"

Step 4: Install (Second Boot)

1. Themed menu appears
2. Select "Install"
3. Accept EULA, select disk, configure partitions
4. At Package Selection, choose "1. Photon MOK Secure Boot"
5. Configure hostname and root password
6. Complete installation and reboot

Troubleshooting Quick Reference

Detailed Troubleshooting

Black screen after "UEFI Secure Boot is enabled" message (Installed System):

• Root Cause (v1.9.0): Installed system received standard kernel (modules as files) instead of custom kernel (USB built-in)
• Fix (v1.9.1+): Tool now injects custom kernel binary/modules into linux-mok RPM, ensuring USB drivers are built-in
• Manual fix (legacy): Regenerate initrd with --add-drivers "usbcore usb-common xhci_hcd xhci_pci ehci_hcd ehci_pci uhci_hcd usb_storage"

linux-mok RPM build fails with depmod "No such file or directory":

• Root Cause (v1.9.1): Spec file determined KVER from vmlinuz filename (e.g., 6.1.159-7.ph5-esx) but custom modules directory has different version (e.g., 6.1.159-esx)
• Fix (v1.9.2+): Spec now detects KVER from actual modules directory instead of vmlinuz filename

MOK packages missing from ISO / "grub2-efi-image-mok package not found" during install:

• Root Cause (pre-1.9.2): Silent copy failures with no verification
• Fix (v1.9.2+): Tool now verifies MOK RPMs exist before copy, validates each copy operation, and confirms packages are in repodata

Laptop shows gray/red security dialog instead of blue MokManager:

• This means CSM/Legacy boot is enabled
• The laptop's firmware is handling the violation, not shim's MokManager
• Fix: Disable CSM completely, enable pure UEFI mode

MOK enrollment appears to succeed but doesn't persist:

• The wrong MokManager is being used (laptop's built-in)
• SUSE shim looks for MokManager at \MokManager.efi (root)
• Fix: Rebuild ISO with latest version (places MokManager correctly)

Installed system gets "bad shim signature":

• Standard VMware packages were installed (have shim_lock)
• Fix: Reinstall and select "1. Photon MOK Secure Boot" at package selection

Installed system boots to emergency mode with "Loading of unsigned module is rejected":

• Root Cause (pre-v1.9.4): RPM's brp-strip strips ELF binaries during package build, which removes PKCS#7 signatures from kernel modules
• Symptoms: System boots past GRUB, kernel loads, then rejects modules (loop, dm_mod, drm, fuse, etc.) and enters emergency mode
• Fix (v1.9.4+): Added %define __strip /bin/true to linux-mok.spec to preserve module signatures
• Diagnosis: tail -c 50 /lib/modules/*/kernel/drivers/block/loop.ko | hexdump -C - signed modules show "Module signature appended" at end

ISO Structure

ISO Root/
├── ENROLL_THIS_KEY_IN_MOKMANAGER.cer    # MOK certificate
├── MokManager.efi                        # SUSE MokManager
├── EFI/BOOT/
│   ├── BOOTX64.EFI                      # SUSE shim
│   ├── grub.efi                         # Custom GRUB stub
│   ├── grubx64.efi                      # Same as grub.efi
│   ├── grubx64_real.efi                 # VMware GRUB (for standard path)
│   └── MokManager.efi                   # Backup
├── boot/grub2/
│   ├── efiboot.img                      # EFI System Partition
│   └── grub.cfg                         # Boot menu
├── RPMS/x86_64/                         # Original + MOK RPMs
└── isolinux/                            # BIOS boot (legacy)
    ├── vmlinuz                          # MOK-signed kernel
    └── initrd.img

Key Locations

/root/hab_keys/
├── MOK.key / MOK.crt / MOK.der          # Machine Owner Key
├── kernel_module_signing.pem             # Kernel module signing key
├── shim-suse.efi                        # SUSE shim (embedded)
├── MokManager-suse.efi                  # SUSE MokManager (embedded)
├── grub-photon-stub.efi                 # Custom GRUB stub (MOK-signed)
├── vmlinuz-mok                          # MOK-signed kernel
└── RPM-GPG-KEY-habv4                    # GPG public key (if --rpm-signing)

GRUB Modules Included

Essential modules in custom GRUB stub:

• probe - UUID detection for photon.media=UUID=$photondisk
• gfxmenu - Themed menus
• png, jpeg, tga - Background images
• gfxterm_background - Graphics background
• search, configfile, linux, initrd - Core boot
• chain, fat, iso9660, part_gpt - Filesystem/chainload

Embedded Components

SUSE shim components are embedded in data/:

• shim-suse.efi.gz - SUSE shim (Microsoft-signed, SBAT=shim,4)
• MokManager-suse.efi.gz - SUSE MokManager

Extracted automatically during build. No internet required.

Installer Patches

The tool applies several patches to the photon-os-installer in the initrd:

1. Progress Bar Fix (installer.py)

The installer assumes progress_bar exists in exit_gracefully(). Fix:

• Initialize self.progress_bar = None in __init__()
• Check for None before accessing in exit_gracefully() and _execute_modules()

Submitted upstream as PR #39.

2. Linux-MOK Recognition (linuxselector.py)

The LinuxSelector class has hardcoded kernel flavors. Without this patch, selecting packages with linux-mok causes ZeroDivisionError (no menu items created).

Fix: Add "linux-mok": "MOK Secure Boot" to linux_flavors dictionary.

For Developers Using This Skill

What I Can Help With

1. Building ISOs: Run build commands, diagnose failures
2. Understanding architecture: Explain boot chains, signing, verification
3. Modifying code: Add features, fix bugs, update documentation
4. Troubleshooting: Analyze errors, identify root causes
5. Compliance: Explain requirements, implement signing

Example Interactions

Build an ISO:

User: Build a Secure Boot ISO for Photon OS 5.0
[I'll run the build command and report results]

Diagnose issues:

User: My ISO gets "bad shim signature" on my laptop
[I'll explain the cause and provide step-by-step fix]

Modify the tool:

User: Add support for custom GRUB themes
[I'll analyze the code, propose changes, implement and test]

Understand the code:

User: How does the RPM patcher work?
[I'll explain the architecture with code references]

See docs/DROID_SKILL_GUIDE.md for complete developer guide.

Security Measures (v1.8.0)

The tool implements several security measures:

Input Validation

• Path validation: All user-provided paths are validated against shell metacharacters
• Release whitelist: Only valid releases (4.0, 5.0, 6.0) are accepted
• Key size whitelist: Only valid RSA sizes (2048, 3072, 4096) are accepted
• Dangerous character rejection: Paths containing ;|&$\"'and..` are rejected

Secure Temporary Directories

• Uses mkdtemp() instead of predictable /tmp/prefix_PID patterns
• Temp directories created with random suffixes and 0700 permissions
• Prevents symlink attacks and race conditions (TOCTOU mitigation)

Log Sanitization

• Private key paths are masked as [PRIVATE_KEY] in verbose output
• Prevents accidental disclosure of sensitive paths in logs

Certificate Expiration Monitoring

• -C, --check-certs: Check all certificates for expiration status
• -W, --cert-warn=DAYS: Set warning threshold (default: 30 days)
• Reports [OK], [WARNING], [EXPIRED] for each certificate
• Returns exit code 1 if any certificates need attention

# Check certificate status
./PhotonOS-HABv4Emulation-ISOCreator -C

# Warn if certificates expire within 60 days
./PhotonOS-HABv4Emulation-ISOCreator -C --cert-warn=60

Configurable Key Sizes

• -K, --key-bits=BITS: Set RSA key size (2048, 3072, 4096)
• Default: 2048-bit (compatibility)
• Recommended for high security: 4096-bit

# Generate 4096-bit keys valid for 1 year
./PhotonOS-HABv4Emulation-ISOCreator -K 4096 -m 365 -g

Remaining Security Considerations

For production deployments in regulated environments, consider:

1. Adding SHA256 checksum verification for downloads
2. Using hardware security modules (HSM) for key storage