[PATCH master 1/3] common: introduce CONFIG_HAS_INSECURE_DEFAULT

[PATCH master 1/3] common: introduce CONFIG_HAS_INSECURE_DEFAULT

[Ahmad Fatoum]

Unlike the functionality controlled by CONFIG_INSECURE, most
functionality in barebox is not as clear-cut: In secure systems, it's
better to turn off the option, but with enough care, board code may
disable the option later on.

To help with securing barebox, let's identify these options that need a
more thorough look by having them select HAS_INSECURE_DEFAULT.

In the future, we will start selecting HAS_INSECURE_DEFAULT when
hardening options are missing. We may also drop HAS_INSECURE_DEFAULT
again from options that are changed to minimize potential for abuse.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 common/Kconfig        | 49 ++++++++++++++++++++++++++++++++++++++++---
 lib/Kconfig.hardening |  6 ++++++
 net/Kconfig           |  4 ++++
 3 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/common/Kconfig b/common/Kconfig
index 0ce99e98286c..fc29d1ca9427 100644
--- a/common/Kconfig
+++ b/common/Kconfig
@@ -149,9 +149,20 @@ config LOCALVERSION_AUTO
 
 	  which is done within the script "scripts/setlocalversion".)
 
+config HAS_INSECURE_DEFAULT
+	bool
+	help
+	  This is selected by options that have potentially insecure defaults.
+	  Extra care needs to be taken when these options are not disabled
+	  in secure booted systems.
+
+	  Any option selecting this should include in its help text
+	  an explanation of the security considerations.
+
 config INSECURE
 	bool "enable convenient defaults that are unsuitable for secure-booting systems"
 	default y
+	select HAS_INSECURE_DEFAULT
 	help
 	  Say n here when barebox is part of a secure boot chain and you
 	  want to disable defaults that may compromise the boot chain.
@@ -344,13 +355,17 @@ endchoice
 config MODULES
 	depends on HAS_MODULES
 	depends on EXPERIMENTAL
+	select HAS_INSECURE_DEFAULT
 	bool "module support"
 	modules
 	help
 	  This option enables support for loadable modules via insmod. Module
 	  support is quite experimental at the moment. There is no convenient
 	  way to compile modules and the list of exported symbols to actually
-	  make use of modules is short to nonexistent
+	  make use of modules is short to nonexistent.
+
+	  As modules aren't be signed, loading external modules is not
+	  recommended for secure systems.
 
 config HAVE_MOD_ARCH_SPECIFIC
 	bool
@@ -750,6 +765,15 @@ config BOOTM_FORCE_SIGNED_IMAGES
 	  are refused to boot. Effectively this means only FIT images can be booted
 	  since they are the only supported image type that support signing.
 
+config BOOTM_OPTIONAL_SIGNED_IMAGES
+	def_bool !BOOTM_FORCE_SIGNED_IMAGES
+	select HAS_INSECURE_DEFAULT
+	help
+	  With this option enabled, barebox can be reconfigured to not verify signed
+	  images. It's the board code's responsibility to call the function
+	  bootm_force_signed_images() when secure booted to ensure that runtime
+	  reconfiguration is no longer possible.
+
 config BLSPEC
 	depends on FLEXIBLE_BOOTARGS
 	depends on !SHELL_NONE
@@ -964,6 +988,7 @@ source "common/partitions/Kconfig"
 
 config ENV_HANDLING
 	select CRC32
+	select HAS_INSECURE_DEFAULT
 	bool "Support environment files storage"
 	default y if !SHELL_NONE
 	help
@@ -972,6 +997,17 @@ config ENV_HANDLING
 	  the persistent environment, the "loadenv" command (also executed during
 	  startup) will bring them back. If unsure, say yes.
 
+	  As the environment is not cryptographically verified, an attacker with
+	  raw access to the environment storage may set any nv variable and
+	  inject shell scripts to be run by barebox.
+
+	  In general, secure systems should rely exclusively on the barebox
+	  built-in environment, disable the mutable environment and use the
+	  barebox-state framework for persisting a fixed set of variables.
+
+	  A safe use of the mutable environment may be possible if board code only
+	  mounts it after verifying a JSON Web Token that enables a debug mode.
+
 config DEFAULT_ENVIRONMENT
 	select CRC32
 	bool
@@ -1271,8 +1307,9 @@ config OPTEE_SHM_SIZE
 config BOOTM_OPTEE
 	bool
 	prompt "support booting OP-TEE"
-	depends on BOOTM && ARM && 32BIT
+	depends on BOOTM && ARM32
 	select HAVE_OPTEE
+	select HAS_INSECURE_DEFAULT
 	help
 	  OP-TEE is a trusted execution environment (TEE). With this option
 	  enabled barebox supports starting optee_os as part of the bootm command.
@@ -1280,6 +1317,11 @@ config BOOTM_OPTEE
 	  the kernel in nonsecure mode. Pass the optee_os binary with the -t option
 	  or in the global.bootm.tee variable.
 
+	  This mode of late loading OP-TEE just before the kernel is deprecated
+	  in favor of early loading OP-TEE in the PBL (CONFIG_PBL_OPTEE).
+	  Early-loading greatly reduces the attack surface and is the only mode
+	  supported outside of ARMv7.
+
 config PBL_OPTEE
 	bool "Enable OP-TEE early start"
 	depends on ARM
@@ -1307,9 +1349,10 @@ config FASTBOOT_SPARSE
 config FASTBOOT_CMD_OEM
 	bool
 	prompt "Enable OEM commands"
+	select HAS_INSECURE_DEFAULT
 	help
 	  This option enables the fastboot "oem" group of commands. They allow to
-	  executing arbitrary barebox commands and may be disabled in secure
+	  executing arbitrary barebox commands and should be disabled in secure
 	  environments.
 
 endmenu
diff --git a/lib/Kconfig.hardening b/lib/Kconfig.hardening
index 6457d24c7382..53d824af7615 100644
--- a/lib/Kconfig.hardening
+++ b/lib/Kconfig.hardening
@@ -1,5 +1,11 @@
 menu "Hardening options"
 
+if HAS_INSECURE_DEFAULT
+comment "This barebox configuration has CONFIG_HAS_INSECURE_DEFAULT=y indicating"
+comment "that some of the configured options have potentially insecure defaults."
+comment "Extra care needs to be in secure booted systems."
+endif
+
 config BUG_ON_DATA_CORRUPTION
 	bool "Trigger a BUG when data corruption is detected"
 	select DEBUG_LIST
diff --git a/net/Kconfig b/net/Kconfig
index 2491c497bdfc..fc70efb97aa8 100644
--- a/net/Kconfig
+++ b/net/Kconfig
@@ -31,9 +31,13 @@ config NET_NETCONSOLE
 	bool
 	depends on !CONSOLE_NONE
 	prompt "network console support"
+	select HAS_INSECURE_DEFAULT
 	help
 	  This option adds support for a simple udp based network console.
 
+	  This console's communication is not encrypted and is thus not
+	  suitable for use in untrusted networks.
+
 config NET_RESOLV
 	bool
 	prompt "dns support"
-- 
2.39.5

[PATCH master 2/3] Documentation: user: optee: bring up-to-date

[Ahmad Fatoum]

Most platforms now use OP-TEE early loading and we have gained support
to communicate with OP-TEE and not only loading it.

Reflect that in the docs.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/optee.rst | 45 +++++++++++++++++++++++++++---------
 1 file changed, 34 insertions(+), 11 deletions(-)

diff --git a/Documentation/user/optee.rst b/Documentation/user/optee.rst
index 950917b446ad..2729d21d2e44 100644
--- a/Documentation/user/optee.rst
+++ b/Documentation/user/optee.rst
@@ -4,20 +4,20 @@
 OP-TEE
 ======
 
-Barebox is able to start the Open Portable Trusted Execution Environment
-(OP-TEE) either before starting the linux kernel or during lowlevel board
-initialization in the Pre Bootloader ``PBL``.
+barebox has support for loading and communicating with the Open Portable Trusted
+Execution Environment (OP-TEE).
 
-Before Linux start
-------------------
-Enable the `CONFIG_BOOTM_OPTEE` configuration variable and configure the
-`CONFIG_OPTEE_SIZE` variable. This will reserve a memory area at the end
-of memory for OP-TEE to run, usually Barebox would relocate itself there. To
-load OP-TEE before the kernel is started, configure the global ``bootm.tee``
-variable to point to a valid OPTEE v1 binary.
+Loading OP-TEE
+--------------
+
+barebox can start OP-TEE either during lowlevel board initialization
+in the :ref:`prebootloader <pbl>` or prior to starting the linux kernel.
+
+.. _optee_early_loading:
 
 During the PBL
---------------
+^^^^^^^^^^^^^^
+
 To start OP-TEE during the lowlevel initialization of your board in the ``PBL``,
 enable the ``CONFIG_PBL_OPTEE`` configuration variable. your board should then
 call the function ``start_optee_early(void* tee, void* fdt)`` with a valid tee
@@ -27,3 +27,26 @@ Since OP-TEE in the default configuration also modifies the device tree, don't
 pass the barebox internal device tree, instead copy it into a different memory
 location and pass it to OP-TEE afterwards.
 The modified device tree can then be passed to the main barebox start function.
+
+Before Linux start
+^^^^^^^^^^^^^^^^^^
+
+.. warning:: Late loading of OP-TEE is deprecated, greatly increases the
+   attack surface and is only supported on 32-bit ARM systems.
+   Systems should prefer early loading OP-TEE whenever possible.
+
+Enable the `CONFIG_BOOTM_OPTEE` configuration variable and configure the
+`CONFIG_OPTEE_SIZE` variable. This will reserve a memory area at the end
+of memory for OP-TEE to run, usually Barebox would relocate itself there. To
+load OP-TEE before the kernel is started, configure the global ``bootm.tee``
+variable to point to a valid OPTEE v1 binary.
+
+Communication with OP-TEE
+-------------------------
+
+Controlled by the ``CONFIG_OPTEE`` option, barebox has support for
+communicating with OP-TEE via secure monitor calls and dynamic shared memory.
+This is possible independently of whether OP-TEE was loaded by barebox or not.
+
+The primary use cases currently is SCMI-over-OP-TEE, which is required on
+the STM32MP13.
-- 
2.39.5

[PATCH master 3/3] Documentation: user: add security consideration for using barebox

[Ahmad Fatoum]

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@pengutronix.de>
---
 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
+   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.
+
+Note that any list here is bound to be incomplete. The barebox configuration
+needs to be vetted individually according to threat model.
+
+Use of file systems
+^^^^^^^^^^^^^^^^^^^
+
+File systems are among the most complex parser code in barebox and a common
+source of bugs.
+Unlike Linux with its dm-verity support, barebox currently has no way to
+verify a file system before mounting it.
+
+The consequence is that in a verified boot setup, barebox should **never**
+be allowed to mount file systems.
+Especially, :ref:`bootloader spec files <bootloader_spec>` should not be used
+in verified boot setups and signed FIT images **must** be located outside
+a file system and directly in a raw partition.
+
+Configuring barebox
+-------------------
+
+To aid identification of security impact of config options, barebox provides
+two top-level security-related options:
+
+- ``CONFIG_INSECURE``: This enables convenient, but insecure, defaults.
+  Any secure system should disable this option.
+
+- ``CONFIG_HAS_INSECURE_DEFAULT``: This is selected by options that have
+  an outsized potential of compromising security. It's recommended that
+  all configuration options that select ``CONFIG_HAS_INSECURE_DEFAULT``
+  are disabled.
+  If not possible, special care needs to be taken in vetting the insecure
+  defaults in question.
+
+Compile-time configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Any code that's eliminated at compile-time is code that can't be exploited by
+an attacker. It's thus strongly advisable to keep a separate secure
+configuration that disables all features that are used for development and
+are not absolutely necessary for booting in the field.
+
+Run-time configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+It's sometimes desirable to retain some ability to debug locked down systems.
+While attractive, it's not recommended to retain an insecure bootloader for
+the purposes of debugging due to the risk of this bootloader being leaked.
+
+Instead, it's recommended that debugging images are signed specifically to
+target only a specific board.
+
+This is sometimes supported out-of-the-box by the SoC like with the HABv4
+field return feature.
+
+In the generic case, barebox supports verification of JSON Web Tokens against
+a compiled-in RSA public key. Board code should read the JSON Web Token
+(e.g., from a raw partition on a USB mass storage device), verify the
+serial number claim within against the board's actual serial number and only
+then unlock any debugging functionality.
-- 
2.39.5

[PATCH] fixup! Documentation: user: add security consideration for using barebox

[Ahmad Fatoum]

Actually reference the file...

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/user-manual.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 565e6c11f82f..83ba9e4c3505 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -28,6 +28,7 @@ Contents:
    booting-linux
    bootchooser
    remote-control
+   security
    system-setup
    reset-reason
    system-reset
-- 
2.39.5

Re: [PATCH master 3/3] Documentation: user: add security consideration for using barebox

[Sascha Hauer]

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@pengutronix.de>
> ---
>  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 |

Re: [PATCH master 3/3] Documentation: user: add security consideration for using barebox

[Marco Felsch]

Hi Ahmad,

thanks for your patches!

On 25-02-14, 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@pengutronix.de>

you can add my

Reviewed-by: Marco Felsch <m.felsch@pengutronix.de>

for the whole series.

Regards,
  Marco


> ---
>  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
> +   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.
> +
> +Note that any list here is bound to be incomplete. The barebox configuration
> +needs to be vetted individually according to threat model.
> +
> +Use of file systems
> +^^^^^^^^^^^^^^^^^^^
> +
> +File systems are among the most complex parser code in barebox and a common
> +source of bugs.
> +Unlike Linux with its dm-verity support, barebox currently has no way to
> +verify a file system before mounting it.
> +
> +The consequence is that in a verified boot setup, barebox should **never**
> +be allowed to mount file systems.
> +Especially, :ref:`bootloader spec files <bootloader_spec>` should not be used
> +in verified boot setups and signed FIT images **must** be located outside
> +a file system and directly in a raw partition.
> +
> +Configuring barebox
> +-------------------
> +
> +To aid identification of security impact of config options, barebox provides
> +two top-level security-related options:
> +
> +- ``CONFIG_INSECURE``: This enables convenient, but insecure, defaults.
> +  Any secure system should disable this option.
> +
> +- ``CONFIG_HAS_INSECURE_DEFAULT``: This is selected by options that have
> +  an outsized potential of compromising security. It's recommended that
> +  all configuration options that select ``CONFIG_HAS_INSECURE_DEFAULT``
> +  are disabled.
> +  If not possible, special care needs to be taken in vetting the insecure
> +  defaults in question.
> +
> +Compile-time configuration
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Any code that's eliminated at compile-time is code that can't be exploited by
> +an attacker. It's thus strongly advisable to keep a separate secure
> +configuration that disables all features that are used for development and
> +are not absolutely necessary for booting in the field.
> +
> +Run-time configuration
> +^^^^^^^^^^^^^^^^^^^^^^
> +
> +It's sometimes desirable to retain some ability to debug locked down systems.
> +While attractive, it's not recommended to retain an insecure bootloader for
> +the purposes of debugging due to the risk of this bootloader being leaked.
> +
> +Instead, it's recommended that debugging images are signed specifically to
> +target only a specific board.
> +
> +This is sometimes supported out-of-the-box by the SoC like with the HABv4
> +field return feature.
> +
> +In the generic case, barebox supports verification of JSON Web Tokens against
> +a compiled-in RSA public key. Board code should read the JSON Web Token
> +(e.g., from a raw partition on a USB mass storage device), verify the
> +serial number claim within against the board's actual serial number and only
> +then unlock any debugging functionality.
> -- 
> 2.39.5
> 
> 
>