wolfBoot can now read a signed firmware image from a file on a filesystem. This applies to the disk boot path, which covers SD cards, eMMC, SATA and NVMe targets. The feature is read only, optional, and off by default.
What it does
wolfBoot has supported MBR and GPT partition tables on disk targets for some time. A boot slot named a partition, and the signed image had to start at the beginning of that partition, written with dd. The partition itself can sit anywhere on the media, but within it the image always begins at offset zero. That works, and it stays supported, but it makes boot media harder to build and to update, because the image is invisible to ordinary tools.
With the new DISK_FS option, a boot slot can name a file path instead. Set BOOT_FILE_A and BOOT_FILE_B to something like /boot/os.itb, and wolfBoot resolves that path on the partition and loads the image from the file. FAT32 and ext4 are the two most common filesystems on embedded boot media, which is why they were chosen first.
Nothing in the security model changes. The file holds an ordinary wolfBoot signed image, with the manifest header at the start of the file and the payload after it. Signing, A/B version selection, anti rollback and disk encryption all work exactly as before. A partition holding no recognized filesystem is still read raw, so turning the option on does not disturb an existing layout.
Features
- FAT32 and ext4, either one or both in the same build.
- Long filenames on FAT32, including nested paths.
- Extent mapped files on ext4, which is what every modern mkfs.ext4 produces.
- Sparse files read correctly. A hole reads as zeros, which is exactly what ext4 defines a hole to be, so the signature still covers precisely what the file contains. This matters in practice, because mke2fs and cp punch a hole wherever the source has a run of zeros, and the padding in a signed image header always does.
- Stock volumes work as is. A volume from a plain mkfs.vfat -F 32 or mkfs.ext4 is readable with no special options. The common ext4 feature set of 64bit, metadata_csum and flex_bg is supported.
- Mixed slots. Slot A can live on a FAT32 partition while slot B lives on ext4.
- Partition selection by index or by label. wolfBoot matches the GPT partition name first, then falls back to the FAT32 or ext4 volume label. That fallback means label based selection also works on MBR disks, which have no partition names at all.
- Big-endian and little-endian hosts. Every on-disk field is read byte-wise, in the partition table as well as in the filesystems, so the whole disk path is endian neutral.
- Bounded parsing. All filesystem metadata is read before the image signature is checked, so every structure that can reference another structure is bounded. Cluster chains, extent trees and directory walks all terminate on crafted input.
File System design limitations
The following features are uncommon and not supported yet (if you are interested please request). If a filesystem is detected with any of these wolfBoot properly detects and reports unsupported for these.
- FAT12 and FAT16.
- ext2 and ext3, which use the older indirect block map instead of extents.
- Symbolic links, inline_data, ext4 encryption and compression, and uninitialized extents.
- Logical sector sizes other than 512 bytes.
- ext4 volumes larger than 16 TiB.
- Volumes with a dirty journal, unless WOLFBOOT_FS_EXT4_ALLOW_DIRTY is set.
- Writing. The layer is read only by design.
Build options
DISK_FS selects which parsers are compiled in:
| Setting | Result |
|---|---|
| Unset (default) | Raw partition access only, unchanged from before |
| DISK_FS=fat32 | FAT32 only |
| DISK_FS=ext4 | ext4 only |
| DISK_FS=both | Both, chosen automatically per partition |
DISK_FS requires a disk boot target, meaning DISK_SDCARD=1, DISK_EMMC=1, or an x86 FSP and AHCI target.
Partition tables need no option at all. wolfBoot reads sector zero, detects a protective MBR and parses the GPT if one is present, and otherwise parses the MBR table. Both formats are supported automatically on every disk target.
Two further knobs are available. WOLFBOOT_FS_CACHE_SIZE sets the metadata cache, which defaults to 512 bytes. DEBUG_FS=1 traces mount and lookup decisions.
Code size
Measured on a ZynqMP SD card configuration, AArch64 at -Os, as .text bytes:
| Build | .text | Added |
|---|---|---|
| Baseline, no DISK_FS | 68,328 | |
| DISK_FS=fat32 | 73,076 | +4,748 |
| DISK_FS=ext4 | 73,756 | +5,428 |
| DISK_FS=both | 76,524 | +8,196 |
Building only the filesystem you actually deploy saves roughly 3 KB against building both.
Tested platforms
Validated on hardware on six targets, chosen to cover different parts of the matrix rather than to repeat the same test.
| Vendor | Board | Architecture | Table | What it covers |
|---|---|---|---|---|
| Intel | x86 FSP (QEMU, AHCI) | x86 | GPT | FAT32 and ext4 in one boot |
| AMD | ZCU102 | AArch64 | MBR | RSA4096 with SHA3-384, 1 KiB ext4 blocks |
| AMD | ZC702 | ARMv7-A | MBR | Slow controller, SDHCI at 6 MHz |
| AMD | Versal VMK180 | AArch64 | MBR | PIO transfers, and a sparse ext4 file |
| Microchip | PolarFire MPFS250 | RISC-V | GPT | GPT partition label selection |
| NXP | QorIQ T1040 RDB | PowerPC e5500 | MBR | Big endian, on real silicon rather than emulation |
Between them these cover both partition table formats, both label mechanisms, all three ext4 block sizes, both SDHCI transfer modes, four signature algorithms, five architectures, and both byte orders.
Testing also includes 160 unit checks across six suites, clean under AddressSanitizer, and a host side harness in tools/fs-test that runs the real parsers against real filesystem images built by mkfs. That harness needs no root and no loopback mounts, so it is easy to point at your own media. It also runs the same images as big endian PowerPC under emulation, covering the partition table and both filesystems, and that runs in CI so the property stays true.
Enabling it
DISK_FS=both CFLAGS_EXTRA+=-DBOOT_FILE_A='"/boot/os.itb"' CFLAGS_EXTRA+=-DBOOT_FILE_B='"/boot/os.itb"'
See docs/compile.md for the full set of options.
The implementation, including the tests and hardware results described above, is in wolfBoot pull request #872.
Questions
If you would like to talk through how filesystem based boot fits your product, or you have a board or a filesystem you would like to see supported, we would be glad to hear from you. Please contact us at facts@wolfssl.com or call us at +1 425 245 8247, and our engineering team is always happy to help.
Download wolfSSL Now