diff mbox series

[v5] ref-manual: variable FIT_SIGN_INDIVIDUAL mix-and-match attacks

Message ID 20250313211435.3042719-1-adrian.freihofer@siemens.com
State New
Headers show
Series [v5] ref-manual: variable FIT_SIGN_INDIVIDUAL mix-and-match attacks | expand

Commit Message

Adrian Freihofer March 13, 2025, 9:14 p.m. UTC
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.

Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
---
 documentation/ref-manual/variables.rst | 32 +++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 6 deletions(-)
diff mbox series

Patch

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 861b04eaab1..4a85de9586e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3170,13 +3170,33 @@  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.
+      However, 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
+      still ensured. At runtime, these hashes are verified against newly
+      computed hashes, ensuring integrity.
+
+      Enabling :term:`FIT_SIGN_INDIVIDUAL` typically increases complexity for
+      no benefit, except for image nodes that are not referenced by any
+      configuration node, which would otherwise remain unsigned.
+      For most use cases, it is recommended to keep this variable set to "0".
+
+      For further details, refer to the official U-Boot documentation:
+      `U-Boot fit signature <https://docs.u-boot.org/en/latest/usage/fit/signature.html>`__
+      and more specifically at:
+      `U-Boot signed configurations <https://docs.u-boot.org/en/latest/usage/fit/signature.html#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.