From 7f3dbf4f84bc5efd4b55459972ecb4808fe0fb6f Mon Sep 17 00:00:00 2001 From: Adrian Freihofer Date: Mon, 17 Mar 2025 18:35:01 +0100 Subject: [PATCH] ref-manual: variable FIT_SIGN_INDIVIDUAL mix-and-match attacks Incorporate the lessons learned from a regression introduced with commit OE-Core rev: 259bfa86f384206f0d0a96a5b84887186c5f689e u-boot: kernel-fitimage: Fix dependency loop if UBOOT_SIGN_ENABLE and UBOOT_ENV enabled and fixed with commit OE-Core rev: 0106e5efab99c8016836a2ab71e2327ce58a9a9d u-boot: kernel-fitimage: Restore FIT_SIGN_INDIVIDUAL="1" behavior into the documentation. The use of the variable FIT_SIGN_INDIVIDUAL is explicitly discouraged. (From yocto-docs rev: d34e1d4e3f229bcd6560fe7df544869b0cd9875f) Signed-off-by: Adrian Freihofer Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/ref-manual/variables.rst | 34 +++++++++++++++++++++----- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 861b04eaab..5b5eaccc2a 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -3170,13 +3170,35 @@ system and gives an overview of their function and contents. :ref:`ref-classes-kernel-fitimage` class. :term:`FIT_SIGN_INDIVIDUAL` - If set to "1", then the :ref:`ref-classes-kernel-fitimage` - class will sign the kernel, dtb and ramdisk images individually in addition - to signing the FIT image itself. This could be useful if you are - intending to verify signatures in another context than booting via - U-Boot. + If set to "1", the :ref:`ref-classes-kernel-fitimage` class signs each + image node individually, including the kernel, DTB, RAM disk, and any + other image types present in the FIT image, in addition to signing the + configuration nodes. + This can be useful if you need to verify signatures outside of the + U-Boot boot process. By default, this variable is set to "0". - This variable is set to "0" by default. + If :term:`UBOOT_SIGN_ENABLE` is set to "1" and + :term:`FIT_SIGN_INDIVIDUAL` remains at its default value of "0", only the + configuration nodes are signed. Since configuration nodes include hashes + of their referenced image nodes, the integrity of the entire FIT image is + ensured as long as the image nodes are loaded via the configuration nodes + and the hashes of the image nodes are checked. That's usually the case. + + Enabling :term:`FIT_SIGN_INDIVIDUAL` typically increases complexity for + little benefit. There might be exceptions such as image nodes that are + not referenced by any configuration node or loaded directly for whatever + reason. + For most use cases, setting this variable to "0" provides sufficient + security. + + For further details, refer to the official U-Boot documentation: + `U-Boot fit signature `__ + and more specifically at: + `U-Boot signed configurations `__. + + Signing only the image nodes is intentionally not implemented by + :term:`OpenEmbedded-Core (OE-Core)`, as it is vulnerable to mix-and-match + attacks. :term:`FIT_SIGN_NUMBITS` Size of the private key used in the FIT image, in number of bits.