barebox,state on the EFI payload: boot-disk binding and state.dtb trust

barebox,state on the EFI payload: boot-disk binding and state.dtb trust

[Raymond | KelvaneOS]

Hi,

We are evaluating barebox as the boot selector for an immutable Linux
distribution on UEFI x86-64, with A/B generations and barebox,state in a
dedicated GPT partition. Two things in the EFI payload I could not settle
from the source, and I would rather ask than guess.

1) Binding state to the boot disk

We want the state backend to resolve to a partition on the disk barebox
was loaded from, without baking a machine-specific PARTUUID into the
device tree.

barebox,bootsource together with storage-by-alias looks like the intended
composition, and state.c already resolves a whole-disk backend to the
state partition by GPT type GUID. But bootsource_get_alias_stem() in
common/bootsource.c has no case for BOOTSOURCE_HD or BOOTSOURCE_USB, so
bootsource_of_node_get() returns NULL on the paths the EFI payload uses.

Is there an intended mechanism here that I have missed? If not, would a
patch adding those bootsource cases be welcome, or were they left out for
a reason?

2) Trusting state.dtb under Secure Boot

efi/payload/init.c reads the state description from
/boot/EFI/barebox/state.dtb when CONFIG_STATE is enabled and /boot is
mounted. That file is not covered by the signature on the barebox EFI
binary, so with Secure Boot enabled and our own keys enrolled, the layout
and storage association of the state area remain modifiable while the
rest of the chain is authenticated.

Is there an existing way to require a built-in state description instead,
or to authenticate that file? If not, would a Kconfig option to disable
the external load path be acceptable?

Happy to do the work on either if the direction is agreed.

Thanks,
Raymond Zwarts

Re: barebox,state on the EFI payload: boot-disk binding and state.dtb trust

[Ahmad Fatoum]

Hello Raymond,

On 7/28/26 2:45 PM, Raymond | KelvaneOS wrote:
> Hi,
> 
> We are evaluating barebox as the boot selector for an immutable Linux
> distribution on UEFI x86-64, with A/B generations and barebox,state in a
> dedicated GPT partition. Two things in the EFI payload I could not settle
> from the source, and I would rather ask than guess.
> 
> 1) Binding state to the boot disk
> 
> We want the state backend to resolve to a partition on the disk barebox
> was loaded from, without baking a machine-specific PARTUUID into the
> device tree.

Most systems running barebox store the state on some "built-in" storage,
so having a dynamic location was not a common use case.

> barebox,bootsource together with storage-by-alias looks like the intended
> composition, and state.c already resolves a whole-disk backend to the
> state partition by GPT type GUID. But bootsource_get_alias_stem() in
> common/bootsource.c has no case for BOOTSOURCE_HD or BOOTSOURCE_USB, so
> bootsource_of_node_get() returns NULL on the paths the EFI payload uses.
> 
> Is there an intended mechanism here that I have missed? If not, would a
> patch adding those bootsource cases be welcome, or were they left out for
> a reason?

Patches are most certainly welcome, but merely adding aliases won't cut
it as this logic relies on both barebox and Linux using device trees
that unambiguously identify the boot devices.

Do you have a scheme in mind on how to detect the boot medium in x86
Linux without depending on a UUID stored to the medium?

> 2) Trusting state.dtb under Secure Boot
> 
> efi/payload/init.c reads the state description from
> /boot/EFI/barebox/state.dtb when CONFIG_STATE is enabled and /boot is
> mounted. That file is not covered by the signature on the barebox EFI
> binary, so with Secure Boot enabled and our own keys enrolled, the layout
> and storage association of the state area remain modifiable while the
> rest of the chain is authenticated.

Are you going to authenticate the state via HMAC?

We are fuzzing the DT parser because it's used for FIT images, but we
indeed didn't so far we treat the state layout definition as untrusted
input.

> Is there an existing way to require a built-in state description instead,
> or to authenticate that file? If not, would a Kconfig option to disable
> the external load path be acceptable?

On device-tree enabled systems, barebox fixed it up into the kernel
device tree. As we only support UEFI boot on x86, we could achieve
something similar via volatile EFI variables with runtime access:

barebox already sets LoaderTimeInitUSec or LoaderFirmwareInfo, so we can
pass the device tree similarly under the barebox GUID.

How about:

- barebox includes an empty device tree by default
- CONFIG_EXTERNAL_DTS_FRAGMENTS can be used to add the state layout
definition from outside the build
- barebox simply passes its internal DT in flattened form via the EFI
variable

> Happy to do the work on either if the direction is agreed.

Sounds great!

Are you going to use UKI profiles? If so, I could collect some thoughts
on how to make this more ergonomic.

Cheers,
Ahmad

> 
> Thanks,
> Raymond Zwarts
> 
> 

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

Re: barebox,state on the EFI payload: boot-disk binding and state.dtb trust

[Raymond | KelvaneOS]

Hello Ahmad,

> Patches are most certainly welcome, but merely adding aliases won't cut
> it as this logic relies on both barebox and Linux using device trees
> that unambiguously identify the boot devices.
>
> Do you have a scheme in mind on how to detect the boot medium in x86
> Linux without depending on a UUID stored to the medium?

You are right; adding alias stems alone does not establish a shared
device identity. Sorry, that suggestion was incomplete.

I was also imprecise about UUIDs: the requirement is to avoid a
per-installation PARTUUID in the build input, not to avoid runtime GPT
identifiers.

The patch I have in mind would resolve
efi_loaded_image->device_handle to the corresponding whole-disk cdev,
enumerate state-type partitions on that disk, require exactly one, and
fix the selected partition's runtime identity into the internal DT
exported through the EFI variable you propose below.

A non-block-backed/GPT origin or a match count other than one is an
error. The resolver would not scan other disks or select the first
match; KelvaneOS would treat the error as fatal rather than continue
with default state.

Linux would consume the fixed-up description and would not need to
reconstruct the EFI device hierarchy.

> Are you going to authenticate the state via HMAC?

Yes. HMAC itself is not an x86 issue. The unresolved part is provisioning
a protected shared secret to both barebox and the Linux writer.

The dt-utils provider I found is tied to CAAM/blob_gen. A key file on
the medium would work functionally but would not meet the offline
tampering threat model. Is a new secret-provider abstraction in
dt-utils the preferred direction for x86?

This is separate from trusting state.dtb: that description selects the
backend, layout and algo, so it can redirect the state or remove HMAC
before the state is authenticated.

> We are fuzzing the DT parser because it's used for FIT images, but we
> indeed didn't so far we treat the state layout definition as untrusted
> input.

My concern is the valid-input case: a well-formed replacement can still
change those semantics.

> On device-tree enabled systems, barebox fixed it up into the kernel
> device tree. As we only support UEFI boot on x86, we could achieve
> something similar via volatile EFI variables with runtime access:
>
> barebox already sets LoaderTimeInitUSec or LoaderFirmwareInfo, so we can
> pass the device tree similarly under the barebox GUID.
>
> How about:
>
> - barebox includes an empty device tree by default
> - CONFIG_EXTERNAL_DTS_FRAGMENTS can be used to add the state layout
> definition from outside the build
> - barebox simply passes its internal DT in flattened form via the EFI
> variable

Yes, that addresses the layout issue cleanly. I had missed
CONFIG_EXTERNAL_DTS_FRAGMENTS as the built-in source; thanks.

For the Secure Boot configuration, the external ESP state.dtb must not
remain an alternative source when a built-in state description is
present. Would you prefer the built-in state node to suppress that path
automatically, or a separate Kconfig guard?

I would keep the HMAC key-provider work separate from the EFI disk
binding and DT handoff.

> Are you going to use UKI profiles? If so, I could collect some thoughts
> on how to make this more ergonomic.

We will use signed UKIs. Profiles are under evaluation; the A/B
generations themselves will remain separate UKIs. Your thoughts would
be very welcome.

Thanks,
Raymond Zwarts

Re: barebox,state on the EFI payload: boot-disk binding and state.dtb trust

[Ahmad Fatoum]

Hi Raymond,

On 8/5/26 9:24 PM, Raymond | KelvaneOS wrote:
> Hello Ahmad,
> 
>> Patches are most certainly welcome, but merely adding aliases won't cut
>> it as this logic relies on both barebox and Linux using device trees
>> that unambiguously identify the boot devices.
>>
>> Do you have a scheme in mind on how to detect the boot medium in x86
>> Linux without depending on a UUID stored to the medium?
> 
> You are right; adding alias stems alone does not establish a shared
> device identity. Sorry, that suggestion was incomplete.
> 
> I was also imprecise about UUIDs: the requirement is to avoid a
> per-installation PARTUUID in the build input, not to avoid runtime GPT
> identifiers.
> 
> The patch I have in mind would resolve
> efi_loaded_image->device_handle to the corresponding whole-disk cdev,
> enumerate state-type partitions on that disk, require exactly one, and
> fix the selected partition's runtime identity into the internal DT
> exported through the EFI variable you propose below.

What's a runtime identity? The disk's UUID?

> A non-block-backed/GPT origin or a match count other than one is an
> error. The resolver would not scan other disks or select the first
> match; KelvaneOS would treat the error as fatal rather than continue
> with default state.

Fair enough.

> Linux would consume the fixed-up description and would not need to
> reconstruct the EFI device hierarchy.
> 
>> Are you going to authenticate the state via HMAC?
> 
> Yes. HMAC itself is not an x86 issue. The unresolved part is provisioning
> a protected shared secret to both barebox and the Linux writer.

Yes.

> The dt-utils provider I found is tied to CAAM/blob_gen. A key file on
> the medium would work functionally but would not meet the offline
> tampering threat model. Is a new secret-provider abstraction in
> dt-utils the preferred direction for x86?

The functionality of the out-of-tree blob_gen driver is now available
upstream in Linux as a trusted key source/backend.

It would be really nice if we had a generic method of pointing at the
blob as a DT partition and a generic dt-utils secret provider would take
that, load it as trusted key and use it for HMAC.

Use it for HMAC might be a bit tricky. We would need to either derive
some secret that can be exported to userspace or to use AF_ALG with a
key in the kernel keyring. Not sure if either is possible, but I think
something along these lines would be cool.

That said, if the kernel doesn't expose the necessary glue yet, I would
take patches that add a new secret provider.

> This is separate from trusting state.dtb: that description selects the
> backend, layout and algo, so it can redirect the state or remove HMAC
> before the state is authenticated.
>
>> We are fuzzing the DT parser because it's used for FIT images, but we
>> indeed didn't so far we treat the state layout definition as untrusted
>> input.
> 
> My concern is the valid-input case: a well-formed replacement can still
> change those semantics.

Ack

>> On device-tree enabled systems, barebox fixed it up into the kernel
>> device tree. As we only support UEFI boot on x86, we could achieve
>> something similar via volatile EFI variables with runtime access:
>>
>> barebox already sets LoaderTimeInitUSec or LoaderFirmwareInfo, so we can
>> pass the device tree similarly under the barebox GUID.
>>
>> How about:
>>
>> - barebox includes an empty device tree by default
>> - CONFIG_EXTERNAL_DTS_FRAGMENTS can be used to add the state layout
>> definition from outside the build
>> - barebox simply passes its internal DT in flattened form via the EFI
>> variable
> 
> Yes, that addresses the layout issue cleanly. I had missed
> CONFIG_EXTERNAL_DTS_FRAGMENTS as the built-in source; thanks.

It's not a built-in source per se, but the files specified there are
included after barebox' own built-in DT.

> For the Secure Boot configuration, the external ESP state.dtb must not
> remain an alternative source when a built-in state description is
> present. Would you prefer the built-in state node to suppress that path
> automatically, or a separate Kconfig guard?

built-in state should always take precedence over the external.
We can add a Kconfig option to control this later should a need arise.

> I would keep the HMAC key-provider work separate from the EFI disk
> binding and DT handoff.

Sure.

>> Are you going to use UKI profiles? If so, I could collect some thoughts
>> on how to make this more ergonomic.
> 
> We will use signed UKIs. Profiles are under evaluation; the A/B
> generations themselves will remain separate UKIs. Your thoughts would
> be very welcome.

A UKI is detected as an EFI application, so global.linux.bootargs.*
isn't serialized into load options for it.

Analogous to global.linux.bootargs.*, I think we should probably add
global.efi.bootargs.* that are concatenated (lexicographically as with
linux.bootargs) as load options.

EFI binaries that filetype_is_linux_efi_image() returns true for will
have as load options the EFI options followed by the Linux options, but
non-kernel images will just have the EFI options.

That way you can have barebox select a profile (@1/@2 at the start of
the load options).

Cheers,
Ahmad

> 
> Thanks,
> Raymond Zwarts
> 

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

Re: barebox,state on the EFI payload: boot-disk binding and state.dtb trust

[Raymond | KelvaneOS]

Hello Ahmad,

> What's a runtime identity? The disk's UUID?

Yes, the containing disk's GPT DiskGUID. "Runtime identity" was
imprecise; I did not mean the partition's PARTUUID.

> We would need to either derive some secret that can be exported to
> userspace or to use AF_ALG with a key in the kernel keyring.

Linux 6.12's AF_ALG supports ALG_SET_KEY_BY_KEY_SERIAL for keyed hashes
and accepts trusted keys. That gives us a Linux-side path to evaluate,
but dt-utils does not implement that provider. AF_ALG is now deprecated
upstream, so it should remain an implementation detail rather than the
provider interface.

> It's not a built-in source per se, but the files specified there are
> included after barebox' own built-in DT.
>
> built-in state should always take precedence over the external.
> We can add a Kconfig option to control this later should a need arise.

Understood. That precedence is sufficient for KelvaneOS; we do not need
another Kconfig option now.

> Analogous to global.linux.bootargs.*, I think we should probably add
> global.efi.bootargs.* [...]
>
> That way you can have barebox select a profile (@1/@2 at the start of
> the load options).

That fits. A/B generations will remain separate UKIs; if we use
profiles, the proposed EFI bootargs can carry the profile selector.

Thanks,
Raymond Zwarts

> On 5 Aug 2026, at 21:24, Raymond | KelvaneOS <raymond@kelvaneos.eu> wrote:
> 
> Hello Ahmad,
> 
>> Patches are most certainly welcome, but merely adding aliases won't cut
>> it as this logic relies on both barebox and Linux using device trees
>> that unambiguously identify the boot devices.
>> 
>> Do you have a scheme in mind on how to detect the boot medium in x86
>> Linux without depending on a UUID stored to the medium?
> 
> You are right; adding alias stems alone does not establish a shared
> device identity. Sorry, that suggestion was incomplete.
> 
> I was also imprecise about UUIDs: the requirement is to avoid a
> per-installation PARTUUID in the build input, not to avoid runtime GPT
> identifiers.
> 
> The patch I have in mind would resolve
> efi_loaded_image->device_handle to the corresponding whole-disk cdev,
> enumerate state-type partitions on that disk, require exactly one, and
> fix the selected partition's runtime identity into the internal DT
> exported through the EFI variable you propose below.
> 
> A non-block-backed/GPT origin or a match count other than one is an
> error. The resolver would not scan other disks or select the first
> match; KelvaneOS would treat the error as fatal rather than continue
> with default state.
> 
> Linux would consume the fixed-up description and would not need to
> reconstruct the EFI device hierarchy.
> 
>> Are you going to authenticate the state via HMAC?
> 
> Yes. HMAC itself is not an x86 issue. The unresolved part is provisioning
> a protected shared secret to both barebox and the Linux writer.
> 
> The dt-utils provider I found is tied to CAAM/blob_gen. A key file on
> the medium would work functionally but would not meet the offline
> tampering threat model. Is a new secret-provider abstraction in
> dt-utils the preferred direction for x86?
> 
> This is separate from trusting state.dtb: that description selects the
> backend, layout and algo, so it can redirect the state or remove HMAC
> before the state is authenticated.
> 
>> We are fuzzing the DT parser because it's used for FIT images, but we
>> indeed didn't so far we treat the state layout definition as untrusted
>> input.
> 
> My concern is the valid-input case: a well-formed replacement can still
> change those semantics.
> 
>> On device-tree enabled systems, barebox fixed it up into the kernel
>> device tree. As we only support UEFI boot on x86, we could achieve
>> something similar via volatile EFI variables with runtime access:
>> 
>> barebox already sets LoaderTimeInitUSec or LoaderFirmwareInfo, so we can
>> pass the device tree similarly under the barebox GUID.
>> 
>> How about:
>> 
>> - barebox includes an empty device tree by default
>> - CONFIG_EXTERNAL_DTS_FRAGMENTS can be used to add the state layout
>> definition from outside the build
>> - barebox simply passes its internal DT in flattened form via the EFI
>> variable
> 
> Yes, that addresses the layout issue cleanly. I had missed
> CONFIG_EXTERNAL_DTS_FRAGMENTS as the built-in source; thanks.
> 
> For the Secure Boot configuration, the external ESP state.dtb must not
> remain an alternative source when a built-in state description is
> present. Would you prefer the built-in state node to suppress that path
> automatically, or a separate Kconfig guard?
> 
> I would keep the HMAC key-provider work separate from the EFI disk
> binding and DT handoff.
> 
>> Are you going to use UKI profiles? If so, I could collect some thoughts
>> on how to make this more ergonomic.
> 
> We will use signed UKIs. Profiles are under evaluation; the A/B
> generations themselves will remain separate UKIs. Your thoughts would
> be very welcome.
> 
> Thanks,
> Raymond Zwarts