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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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
+   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





[Index of Archives]     [Linux Embedded]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [XFree86]

  Powered by Linux