HackBGRT Documentation

To trust only a specific version of HackBGRT, use the Enroll hash from disk option in MOKManager. This is the recommended security practice.

Steps:

1. In the MOK management menu, select Enroll hash from disk and press Enter.
2. Select your disk and press Enter.
3. Navigate the directory structure to find the HackBGRT binary. Typically, the path is EFI/HackBGRT/grubx64.efi.
4. Select grubx64.efi and press Enter.
5. (Optional) Select View key 0 to verify the SHA256 hash.
6. Select Continue and press Enter.
7. When prompted Enroll the key(s)?, select Yes and press Enter.
8. Select Reboot from the main menu to finish.

If you are not using a standard Windows-only setup, use these methods:

Windows-only (without overwriting bootloader):

1. Run setup.exe and choose to install files without enabling them.
2. Manually configure your boot loader to start \EFI\HackBGRT\loader.efi.

Multi-OS (e.g., Linux + Windows):

1. Configure HackBGRT to point to your other boot loader (e.g., boot=\EFI\systemd\systemd-bootx64.efi).
2. Run setup.exe and install as a new EFI boot entry.

Linux-only:

1. Run setup.exe dry-run.
2. Manually copy the files from the dry-run/EFI directory to your [EFI System Partition]/EFI directory.

To trust any binary signed with the HackBGRT certificate, use the Enroll key from disk option. Note that this trusts anything signed by the same certificate.

Steps:

1. In the MOK management menu, select Enroll key from disk and press Enter.
2. Select your disk and press Enter.
3. Navigate the directory structure to find the certificate file. Typically, the path is EFI/HackBGRT/certificate.cer.
4. Select certificate.cer and press Enter.
5. (Optional) Select View key 0 to verify the certificate details (Issuer: CN=HackBGRT Secure Boot Signer, O=Metabolix).
6. Select Continue and press Enter.
7. When prompted Enroll the key(s)?, select Yes and press Enter.
8. Select Reboot from the main menu to finish.

When Secure Boot is enabled, the first boot after installing HackBGRT will trigger a "Verification failed" error. You must use the MOKManager tool (provided by shim) to trust the HackBGRT binaries.

Follow these steps to enter the configuration tool:

1. On the "Verification failed: (0x1A) Security Violation" error screen, select OK and press Enter.
2. When the screen says "Press any key to perform MOK management", press a key quickly to enter the MOKManager program.

HackBGRT uses images to display during boot.

• Single Image: Edit the splash.bmp file in the installer folder.
• Multiple Images: Edit config.txt to define multiple image paths. One will be picked at random during boot.
• Custom Formats: If using non-BMP files (e.g., my.jpg), copy the file to the installer folder and set path=my.jpg in config.txt before running the installer.
• Manual ESP Installation: If copying images manually to the EFI System Partition (ESP), the image must be a 24-bit BMP file with a 54-byte header (TrueColor BMP3).

If you need to install the shim boot loader manually for an x64 architecture, follow these steps:

1. Obtain shim (preferably shim-signed).
2. Rename your existing boot loader to grubx64.efi.
3. Copy shimx64.efi to the location where your original loader was located.
4. Copy mmx64.efi (MOKManager) to the same folder as shimx64.efi.

Boot Process Logic:

• The system starts shimx64.efi (which you renamed to your loader's name).
• shim attempts to load grubx64.efi.
• If grubx64.efi is not trusted, shim launches mmx64.efi to allow MOK management.

HackBGRT reads its configuration from a file named config.txt located in its working directory or the default directory \EFI\HackBGRT. If no command line arguments are provided via the UEFI Shell, the application will attempt to read this file.

Common configuration settings include:

• debug: Enables/disables debug logging.
• log: Enables/disables persistent logging.
• resolution_x / resolution_y: Target screen resolution.
• image.path: Path to the BMP image to use.
• image.action: Action to take with the BGRT (e.g., REPLACE, REMOVE, KEEP).
• image.orientation: Orientation of the image.
• image.x_mode / image.y_mode: Coordinate positioning mode (KEEP, CENTERED, or absolute).
• boot_path: Custom path to the bootloader if the default Microsoft bootloader cannot be used.

If HackBGRT fails to start the next boot image, it will display a failure message and dump the log.

Recovery Steps:

1. If the screen shows HackBGRT has failed, it will attempt to dump the log and wait 15 seconds before exiting.
2. If you cannot boot into Windows, you must use an installation or recovery disk to repair your boot configuration.
3. During a successful boot transition, HackBGRT provides a 15-second window where you can press ESC to cancel the boot process if something seems wrong.

The application looks for its configuration and assets in the following locations:

• Default Directory: \EFI\HackBGRT
• Working Directory: The directory from which the HackBGRT EFI application was loaded.

It specifically looks for config.txt and the BMP image specified in the configuration within these directories.