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

[Marco Felsch <m.felsch@pengutronix.de>]

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