Hi Ahmad, Great stuff, thank you for writing this up. On Fri, Feb 14, 2025 at 03:23:56PM +0100, Ahmad Fatoum wrote: > There are implicit assumptions around use of barebox in secure systems, > which isn't spelt out anywhere, e.g. that FIT images should be located > in raw partitions. > > Let's start by writing down these security considerations. > > Signed-off-by: Ahmad Fatoum <a.fatoum@xxxxxxxxxxxxxx> > --- > Documentation/boards/imx.rst | 2 + > Documentation/user/security.rst | 160 ++++++++++++++++++++++++++++++++ > 2 files changed, 162 insertions(+) > create mode 100644 Documentation/user/security.rst > > diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst > index 13246599838b..b4adb55d1bea 100644 > --- a/Documentation/boards/imx.rst > +++ b/Documentation/boards/imx.rst > @@ -119,6 +119,8 @@ correspond directly to the boot fusemap settings. > > See the section on :ref:`Reboot modes<reboot_mode>` for general information. > > +.. _hab: > + > High Assurance Boot > ^^^^^^^^^^^^^^^^^^^ > > diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst > new file mode 100644 > index 000000000000..507df9a79e84 > --- /dev/null > +++ b/Documentation/user/security.rst > @@ -0,0 +1,160 @@ > +.. _security: > + > +Security Considerations > +======================= > + > +As bootloader, barebox is often used as part of a cryptographically verified > +boot chain. Such a boot chain is only as secure as its weakest link and > +special care needs to be taken while configuring and deploying barebox. > + > +Verified Boot > +------------- > + > +In a cryptographically verified boot chain (henceforth termed "Verified Boot"), > +each boot stage must be verified by the previous boot stage before execution. > + > +At the start of the verification chain lies some hardware root of trust, most > +often a public key (or its hash) that's programmed into one-time-programmable > +(OTP) eFuses while the board is still in the factory. > + > +The SoC's mask ROM (sometime called BootROM) will consult the eFuses and > +use them to verify the first stage bootloader image. From there on, it's > +expected that every boot stage will only boot the next one after verification. > + > +Verification can take many forms: > + > +- The mask ROM provides an API to verify later images against the same key > + used to verify the first boot stage. > + > +- If both first stage and second stage result from the same build, the first > + stage can embed the hash of the second stage. > + > +- The boot stage has an embedded public key which is used to verify the > + signature of the later boot stage. > + > +Verifying barebox itself > +------------------------ > + > +The way that barebox is verified is highly SoC-specific as it's usually done > +by the SoC mask ROM and in some cases by a different first stage bootloader > +like ARM Trusted Firmware. > + > +For some SoCs, like i.MX :ref:`High Assurance Boot <hab>`, the barebox > +build system has built-in support for invoking the necessary external tools > +to sign the boot images. In the general case however, the signing happens > +outside the barebox build system and the integrator needs to ensure that > +the images are signed with the correct keys. > + > +In any case, each individual board must be locked down, i.e., configured to > +only boot correctly signed images. > + > +The latter is often done by writing a different set of eFuses, see for > +example the barebox :ref:`hab command <command_hab>` which does the necessary > +fusing for both HABv4 and AHAB. > + > +.. warning:: barebox commands likes :ref:`hab command <command_hab>` do only s/likes/like/ > + touch the subset of fuses relevant to most users. It's up to the integrators > + to fuse away unneeded functionality like USB recovery or JTAG as needed. > + > +Loading firmware > +---------------- > + > +In systems utilizing the ARM TrustZone, barebox is often tasked with loading > +the secure OS (Usually OP-TEE). After OP-TEE is loaded, the rest of the > +software runs in a less-privileged non-secure or "normal" world. > + > +The installation of OP-TEE (and any higher privileged firmware like ARM Trusted > +Firmware) should happen as early as possible, i.e., within the barebox > +:ref:`prebootloader <pbl>`. Delaying installation of OP-TEE means that most of > +barebox will run with elevated permission, which greatly increases the attack > +surface. > + > +In concrete terms, the deprecated ``CONFIG_BOOTM_OPTEE`` option should be > +disabled in favor of :ref:`loading OP-TEE early <optee_early_loading>`. > + > +Verifying the kernel by barebox > +------------------------------- > + > +barebox can embed one or more RSA or ECDSA public keys that it will use to > +verify signed FIT images. In a verified boot system, barebox should not > +be allowed to boot any images that have not been signed by the correct key. > +This can be enforced by setting ``CONFIG_BOOTM_FORCE_SIGNED_IMAGES=y`` > +and disabling any ways that could use used to override this, e.g.: > + > +- While useful for development, the barebox shell can be used in creative > + ways to circumvent boot restrictions. It's thus advisable to disable > + the shell completely (``CONFIG_SHELL_NONE=y``) or make it non-interactive > + (``CONSOLE_DISABLE_INPUT=y``). This may be coupled with muxing UART RX > + pin as GPIO for maximum effectiveness. > + > +- Anything done interactively by the shell can also be done automatically by > + means of init scripts in the environment. A secure barebox should only > + consult the environment that it has built in and not parse an externally > + located environment. > + This can be enforced by disabling ``CONFIG_ENV_HANDLING``. > + This does not preclude the use of :ref:`Bootchooser` as the > + :ref:`barebox-state framework <state_framework>` can be used independently. > + > +- There are alternative methods of accessing the shell like netconsole, > + or fastboot. These should preferably be disabled or at least not activated > + by default. As the role of the shell in a verified boot scenario is quite big maybe put this under an extra headline? Sascha -- 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 |
