From 7779540f093d8d09ee29e127c8b6a7cc455db27c Mon Sep 17 00:00:00 2001 From: Rasmus Villemoes Date: Tue, 2 Jun 2026 23:30:11 +0200 Subject: image-fit.c: introduce CONTROL_DTB_AS_FIT config knob Having scripts embedded one way or the other in the U-Boot binary means they are automatically verified/trusted by whatever mechanism verifies U-Boot. Writing those scripts in the built-in environment leads to backslatitis and missing or wrong quoting and is generally not very readable or maintainable. Maintaining scripts in external files allows one to have both syntax highlighting and to some extent apply shellcheck on it (though U-Boot's shell is of course not quite POSIX sh, so some '#shellcheck disable' directives are needed). Getting those into the U-Boot binary is then a matter of having a suitable .dtsi file such as / { images { default = "boot"; boot { description = "Bootscript"; data = /incbin/("boot.sh"); type = "script"; compression = "none"; }; factory-reset { description = "Script for performing factory reset"; data = /incbin/("factory-reset.sh"); type = "script"; compression = "none"; }; }; }; and making that part of CONFIG_DEVICE_TREE_INCLUDES, so that U-Boot's control DTB effectively doubles as a FIT image containing a few "script" entries. At run-time, one's default bootcommand can then simply be source ${fdtcontroladdr}:boot Except of course that the control DTB is in fact not quite a FIT image. The lack of timestamp and description properties could potentially be worked around (by just adding those via that same .dtsi), but the no-@ check is not possible to get around. But since the control dtb is by definition trusted, we can make an exception for that particular address, if the new CONTROL_DTB_AS_FIT config option is enabled. One can of course build an ordinary FIT image with those scripts. However, that requires extra steps in the boot command for loading that script from storage, requires one to use "configurations" for pointing at a single script to run, and signing the FIT image using the same key used for verifying the kernel. Moreover, in certain situations, such as bootstrapping/production, there is no place to load that FIT image from, and it is much simpler to just have the necessary scripts be part of the U-Boot image itself. Reviewed-by: Simon Glass Signed-off-by: Rasmus Villemoes --- boot/Kconfig | 13 +++++++++++++ boot/image-fit.c | 24 ++++++++++++++++++------ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/boot/Kconfig b/boot/Kconfig index ae6f09a6ede..19a170957c6 100644 --- a/boot/Kconfig +++ b/boot/Kconfig @@ -103,6 +103,19 @@ config FIT_FULL_CHECK of bugs or omissions in the code. This includes a bad structure, multiple root nodes and the like. +config CONTROL_DTB_AS_FIT + bool "Allow U-Boot's control DTB to act as FIT image" + help + Enable this to exempt U-Boot's control DTB from the sanity + checks done to ensure FIT images are valid. This can for + example be used to embed whole scripts in the control DTB, + that can then be invoked using 'source ${fdtcontroladdr}'. + In a secure boot setup, this is safe, as the control DTB is + necessarily covered by any mechanism verifying U-Boot and + can therefore be trusted. This only affects the case where + the image being checked is gd->fdt_blob. See + doc/develop/devicetree/control.rst for details. + config FIT_SIGNATURE bool "Enable signature verification of FIT uImages" depends on DM diff --git a/boot/image-fit.c b/boot/image-fit.c index b0fcaf6e17f..87427d07d7c 100644 --- a/boot/image-fit.c +++ b/boot/image-fit.c @@ -1664,6 +1664,16 @@ static int fdt_check_no_at(const void *fit, int parent) return 0; } +static int fit_check_images_node(const void *fit) +{ + if (fdt_path_offset(fit, FIT_IMAGES_PATH) < 0) { + log_debug("Wrong FIT format: no images parent node\n"); + return -ENOENT; + } + + return 0; +} + int fit_check_format(const void *fit, ulong size) { int ret; @@ -1676,6 +1686,13 @@ int fit_check_format(const void *fit, ulong size) return -ENOEXEC; } + /* + * For the control DTB to act as a FIT image, we only require + * an /images node. + */ + if (CONFIG_IS_ENABLED(CONTROL_DTB_AS_FIT) && fit == gd_fdt_blob()) + return fit_check_images_node(fit); + if (CONFIG_IS_ENABLED(FIT_FULL_CHECK)) { /* * If we are not given the size, make do with calculating it. @@ -1724,12 +1741,7 @@ int fit_check_format(const void *fit, ulong size) } /* mandatory subimages parent '/images' node */ - if (fdt_path_offset(fit, FIT_IMAGES_PATH) < 0) { - log_debug("Wrong FIT format: no images parent node\n"); - return -ENOENT; - } - - return 0; + return fit_check_images_node(fit); } int fit_conf_find_compat(const void *fit, const void *fdt) -- cgit v1.3.1 From a6369b8bb299aff8d5641fd11d2fcd0214103a18 Mon Sep 17 00:00:00 2001 From: Rasmus Villemoes Date: Tue, 2 Jun 2026 23:30:12 +0200 Subject: doc: develop: add section on embedding scripts inside control DTB Add a section that explains how one can embed scripts in the control DTB and run them from the U-Boot shell, the advantages of doing that compared to using a separately built FIT image, and the configuration knob that must be turned on to allow this to work. Reviewed-by: Simon Glass Signed-off-by: Rasmus Villemoes --- doc/develop/devicetree/control.rst | 58 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst index 634114af59a..7d6117d5c4b 100644 --- a/doc/develop/devicetree/control.rst +++ b/doc/develop/devicetree/control.rst @@ -232,6 +232,64 @@ outside the U-Boot repository. You can use `DEVICE_TREE_INCLUDES` Kconfig option to specify a list of .dtsi files that will also be included when building .dtb files. +Scripts embedded in control DTB +------------------------------- + +The `DEVICE_TREE_INCLUDES` option can also be used to make the control +DTB serve double duty as a FIT image. By including a `scripts.dtsi` +file containing something like:: + + / { + images { + default = "boot"; + boot { + description = "Bootscript"; + data = /incbin/("boot.sh"); + type = "script"; + compression = "none"; + }; + factory-reset { + description = "Script for performing factory reset"; + data = /incbin/("factory-reset.sh"); + type = "script"; + compression = "none"; + }; + }; + }; + +one can call those scripts using the `source` command in the U-Boot shell:: + + source ${fdtcontroladdr}:boot + +or just ``source ${fdtcontroladdr}`` for invoking the default. + +Since one does not need to separately build a "real" FIT image +containing those scripts, this simplifies both the build process and +the boot logic, as the latter does not need to first load the FIT +image from storage. + +Another advantage is that when the bootloader and boot script must be +updated together, it is easier to achieve a guaranteed atomic update +when the boot script is embedded inside the U-Boot binary, instead of +stored separately. + +For the above to work, one must enable the `CONTROL_DTB_AS_FIT` config +option, which will (when the address passed to the `source` command is +the address of U-Boot's control DTB) elide certain sanity checks that +are normally done: With the above `.dtsi` snippet, the control DTB +does not quite become a "real" FIT image - it lacks `timestamp` and +`description` properties, but more importantly, FIT images cannot +contain nodes with `@` in their names (unit addresses) anywhere, and +the control DTB obviously does have such nodes. + +This is not a security problem, as the control DTB is necessarily +trusted. In any secure boot setup where the bootloader is verified, +that mechanism must also include verification of the control DTB. So +in fact, since the scripts embedded this way are then also +automatically verified, it simplifies implementation of secure +boot. When using a separate FIT image, one must build it with +appropriate signatures, just as when building a FIT image containing a +kernel/dtb/initramfs. Devicetree bindings schema checks --------------------------------- -- cgit v1.3.1 From c8a636af67c640e1427e1085c8bada672e48f805 Mon Sep 17 00:00:00 2001 From: Rasmus Villemoes Date: Tue, 2 Jun 2026 23:30:13 +0200 Subject: test: hook up test of allowing control DTB to act as FIT image Add a test demonstrating how one can embed various scripts in the control DTB. Verify that the source command can be used with ${fdtcontroladdr} by itself (invoking the default script), and with : suffix. Check that the scripts themselves can invoke "sibling" scripts. Also verify that without CONTROL_DTB_AS_FIT set, the control DTB is not accepted by the source command. Reviewed-by: Simon Glass Signed-off-by: Rasmus Villemoes --- arch/sandbox/dts/sandbox-boot.sh | 2 ++ arch/sandbox/dts/sandbox-inner.sh | 4 ++++ arch/sandbox/dts/sandbox-outer.sh | 4 ++++ arch/sandbox/dts/sandbox_scripts.dtsi | 24 ++++++++++++++++++++++++ configs/sandbox_defconfig | 2 ++ test/py/tests/test_source.py | 31 +++++++++++++++++++++++++++++++ 6 files changed, 67 insertions(+) create mode 100644 arch/sandbox/dts/sandbox-boot.sh create mode 100644 arch/sandbox/dts/sandbox-inner.sh create mode 100644 arch/sandbox/dts/sandbox-outer.sh create mode 100644 arch/sandbox/dts/sandbox_scripts.dtsi diff --git a/arch/sandbox/dts/sandbox-boot.sh b/arch/sandbox/dts/sandbox-boot.sh new file mode 100644 index 00000000000..4f7fa661151 --- /dev/null +++ b/arch/sandbox/dts/sandbox-boot.sh @@ -0,0 +1,2 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR MIT) +echo "* default script" diff --git a/arch/sandbox/dts/sandbox-inner.sh b/arch/sandbox/dts/sandbox-inner.sh new file mode 100644 index 00000000000..b8fc8f7484b --- /dev/null +++ b/arch/sandbox/dts/sandbox-inner.sh @@ -0,0 +1,4 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +# Some comment. +echo "* inner" diff --git a/arch/sandbox/dts/sandbox-outer.sh b/arch/sandbox/dts/sandbox-outer.sh new file mode 100644 index 00000000000..40294085433 --- /dev/null +++ b/arch/sandbox/dts/sandbox-outer.sh @@ -0,0 +1,4 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR MIT) +echo "* outer 1" +source ${fdtcontroladdr}:inner +echo "* outer 2" diff --git a/arch/sandbox/dts/sandbox_scripts.dtsi b/arch/sandbox/dts/sandbox_scripts.dtsi new file mode 100644 index 00000000000..c800ec39e87 --- /dev/null +++ b/arch/sandbox/dts/sandbox_scripts.dtsi @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: (GPL-2.0+ OR MIT) +/ { + images { + default = "boot"; + boot { + description = "Test boot script"; + data = /incbin/("sandbox-boot.sh"); + type = "script"; + compression = "none"; + }; + outer { + description = "Script testing recursion"; + data = /incbin/("sandbox-outer.sh"); + type = "script"; + compression = "none"; + }; + inner { + description = "Another test script"; + data = /incbin/("sandbox-inner.sh"); + type = "script"; + compression = "none"; + }; + }; +}; diff --git a/configs/sandbox_defconfig b/configs/sandbox_defconfig index ba800f7d19d..bfdc5ee6010 100644 --- a/configs/sandbox_defconfig +++ b/configs/sandbox_defconfig @@ -20,6 +20,7 @@ CONFIG_EFI_CAPSULE_AUTHENTICATE=y CONFIG_EFI_CAPSULE_CRT_FILE="board/sandbox/capsule_pub_key_good.crt" CONFIG_BUTTON_CMD=y CONFIG_FIT=y +CONFIG_CONTROL_DTB_AS_FIT=y CONFIG_FIT_SIGNATURE=y CONFIG_FIT_CIPHER=y CONFIG_FIT_VERBOSE=y @@ -152,6 +153,7 @@ CONFIG_CMD_STACKPROTECTOR_TEST=y CONFIG_CMD_SPAWN=y CONFIG_MAC_PARTITION=y CONFIG_OF_LIVE=y +CONFIG_DEVICE_TREE_INCLUDES="sandbox_scripts.dtsi" CONFIG_ENV_IS_NOWHERE=y CONFIG_ENV_IS_IN_FAT=y CONFIG_ENV_IS_IN_EXT4=y diff --git a/test/py/tests/test_source.py b/test/py/tests/test_source.py index 970d8c79869..29ab804f81b 100644 --- a/test/py/tests/test_source.py +++ b/test/py/tests/test_source.py @@ -34,3 +34,34 @@ def test_source(ubman): ubman.run_command('fdt rm /images default') assert 'Fail' in ubman.run_command('source || echo Fail') assert 'Fail' in ubman.run_command('source \\# || echo Fail') + +@pytest.mark.boardspec('sandbox') +@pytest.mark.buildconfigspec('cmd_echo') +@pytest.mark.buildconfigspec('cmd_source') +@pytest.mark.buildconfigspec('fit') +@pytest.mark.buildconfigspec('control_dtb_as_fit') +def test_source_control_dtb(ubman): + output = ubman.run_command('source ${fdtcontroladdr}') + assert '* default script' in output + + output = ubman.run_command('source ${fdtcontroladdr}:boot') + assert '* default script' in output + + output = ubman.run_command('source ${fdtcontroladdr}:outer') + assert '* outer 1' in output + assert '* inner' in output + assert '* outer 2' in output + + output = ubman.run_command('source ${fdtcontroladdr}:inner') + assert '* outer' not in output + assert '* inner' in output + + assert 'Fail' in ubman.run_command('source ${fdtcontroladdr}:no-such-script || echo Fail') + +@pytest.mark.buildconfigspec('cmd_echo') +@pytest.mark.buildconfigspec('cmd_source') +@pytest.mark.buildconfigspec('fit') +@pytest.mark.notbuildconfigspec('control_dtb_as_fit') +def test_source_reject_control_dtb(ubman): + assert 'Fail' in ubman.run_command('source ${fdtcontroladdr} || echo Fail') + assert 'Fail' in ubman.run_command('source ${fdtcontroladdr}:boot || echo Fail') -- cgit v1.3.1