[PATCH 00/11] Documentation: define a barebox threat model

[PATCH 00/11] Documentation: define a barebox threat model

[Ahmad Fatoum]

The security considerations chapter is written for integrators and
tells them what to configure.

Security researchers may not know how barebox is integrated, so let's
document what we count as a security vulnerability and what's a normal
bug.

Ahmad Fatoum (11):
  Documentation: security: unnest hardening sections from dm-verity
    section
  Documentation: security: clarify development key insecurity
  Documentation: security: require signature verification to be pinned
  Documentation: security: document trust for builtin devicetree
  Documentation: security: clarify the environment section
  Documentation: security: describe shell and environment as trust
    boundary
  Documentation: security: document the barebox update attack surface
  Documentation: security: update for barebox dm-verity support
  Documentation: security: add anchors for the different sections
  Documentation: define a barebox threat model
  README, SECURITY.md: link the threat model and security considerations

 Documentation/user/security.rst     | 189 ++++++++++++------
 Documentation/user/threat-model.rst | 297 ++++++++++++++++++++++++++++
 Documentation/user/user-manual.rst  |   1 +
 README.rst                          |  10 +
 SECURITY.md                         |   6 +
 crypto/Kconfig                      |   8 +
 6 files changed, 456 insertions(+), 55 deletions(-)
 create mode 100644 Documentation/user/threat-model.rst

-- 
2.47.3

[PATCH 02/11] Documentation: security: clarify development key insecurity

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

Should go without saying, but spell it out anyway.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index 657bcd690b8e..e650c03a1023 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -92,7 +92,8 @@ This can be enforced by setting ``CONFIG_BOOTM_FORCE_SIGNED_IMAGES=y``
 and disabling any ways that could be used to override this.
 
 For development convenience ``CONFIG_CRYPTO_BUILTIN_DEVELOPMENT_KEYS``
-can be used to compile well known development keys into the barebox binary.
+can be enabled after enabling ``CONFIG_INSECURE`` to compile well known
+development keys into the barebox binary.
 The private keys for these keys can be found
 `[here] <https://github.com/pengutronix/ptx-code-signing-dev>`__.
 
-- 
2.47.3

[PATCH 03/11] Documentation: security: require signature verification to be pinned

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

global.bootm.verify defaults to "available", which accepts an image that
carries nothing, and "hash" never looks at the configuration signature.

Document that we expect signature to be set and enforced in verified
boot setups.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index e650c03a1023..7160f8f8e3c2 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -91,6 +91,19 @@ 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 be used to override this.
 
+How thoroughly an image is checked is controlled by
+:ref:`global.bootm.verify <magicvar_global_bootm_verify>`. Only ``signature``
+is suitable for verified boot. ``hash`` checks the image hashes, but not the
+configuration signature, so it detects corruption, not tampering. The default
+``available`` verifies whatever the image carries and accepts an image
+carrying nothing.
+
+As a global variable, the setting may be changeable at runtime unless barebox
+is built with ``CONFIG_BOOTM_FORCE_SIGNED_IMAGES=y`` or the
+:ref:`security policy <use_security-policies>` denies
+``SCONFIG_BOOT_UNSIGNED_IMAGES``. Either pins it to ``signature``. This
+will also result in :ref:`command_bootm` refusing to boot any non-FIT images.
+
 For development convenience ``CONFIG_CRYPTO_BUILTIN_DEVELOPMENT_KEYS``
 can be enabled after enabling ``CONFIG_INSECURE`` to compile well known
 development keys into the barebox binary.
-- 
2.47.3

[PATCH 04/11] Documentation: security: document trust for builtin devicetree

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

barebox-dt-2nd.img exists to allow booting barebox like one would boot a
Linux kernel. This is a convenient way to use barebox without modifying
existent firmware, but it's not suitable for use as part of a boot chain
if the device tree hasn't been verified beforehand.

Spell that out in the documentations and also add the missing help text
for CONFIG_CRYPTO_BUILTIN_KEYS.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 17 +++++++++++++++++
 crypto/Kconfig                  |  8 ++++++++
 2 files changed, 25 insertions(+)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index 7160f8f8e3c2..d981d89268c8 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -56,6 +56,23 @@ fusing for both HABv4 and AHAB.
    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.
 
+Ensuring the barebox devicetree is verified
+-------------------------------------------
+
+Whoever controls the devicetree barebox uses for itself can inject RSA keys
+to be used for FIT verification and control what drivers are probed.
+
+The devicetree must therefore be either:
+
+- verified by the previous boot stage before passing it to barebox
+
+- part of a barebox image and thus verified by the previous boot stage
+
+``barebox-dt-2nd.img`` is bootable like a Linux kernel and takes its
+devicetree from the previous stage. It's thus only suitable for verified
+boot if that stage verified the devicetree as well, e.g. because both are
+part of the same signed FIP image.
+
 Loading firmware
 ----------------
 
diff --git a/crypto/Kconfig b/crypto/Kconfig
index 528e9a0d2204..977e502e8a14 100644
--- a/crypto/Kconfig
+++ b/crypto/Kconfig
@@ -130,6 +130,14 @@ config CRYPTO_BUILTIN_KEYS
 	bool "builtin keys"
 	select KEYTOC
 	select IDR
+	help
+	  Compile public keys into barebox. See CRYPTO_PUBLIC_KEYS for how to
+	  specify them and their keyrings.
+
+	  This also enables reading RSA keys from /signature of the devicetree
+	  barebox runs on, like U-Boot does with its control FDT. Such keys
+	  always end up in the "fit" keyring. Prefer compiled-in keys. Either
+	  way, the devicetree must be verified together with barebox.
 
 config CRYPTO_PUBLIC_KEYS
 	depends on CRYPTO_BUILTIN_KEYS
-- 
2.47.3

[PATCH 05/11] Documentation: security: clarify the environment section

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

CONFIG_ENV_HANDLING can be problematic, even when the environment isn't
mutable, i.e. it's simply read from external unauthenticated storage.

Clarify that in the docs.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index d981d89268c8..9a241b0e2e8d 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -140,13 +140,14 @@ In addition, there are alternative methods of accessing the shell like
 netconsole, or fastboot. These should preferably be disabled or at least
 not activated by default.
 
-Disabling mutable environment handling
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Disabling the non-builtin environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Anything done interactively by the shell can also be done automatically by
 means of init scripts in the environment. Even without shell support, the
 non-volatile variables in the environment could be used to reconfigure
-barebox in an insecure manner.
+barebox in an insecure manner or to influence the command line and device
+tree passed to the kernel on boot.
 
 A secure barebox should thus only consult the environment that it has built
 in and not parse an externally located environment.
-- 
2.47.3

[PATCH 06/11] Documentation: security: describe shell and environment as trust boundary

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

Both sections advise disabling the feature without saying why. The shell
validates nothing by design, so whoever reaches it is as trusted as the
boot chain. The environment sets the global variables that select the
boot source, reach the kernel command line and, unless pinned, decide
whether images are verified at all.

Spell that out and mention SCONFIG_ENVIRONMENT_LOAD next to
CONFIG_ENV_HANDLING, for builds that need environment support but must
not load one from media.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index 9a241b0e2e8d..a618c05b1102 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -140,6 +140,12 @@ In addition, there are alternative methods of accessing the shell like
 netconsole, or fastboot. These should preferably be disabled or at least
 not activated by default.
 
+barebox places no restrictions on what the shell does: a command that writes
+a partition, sets a variable or applies a devicetree overlay does exactly
+that. Whoever reaches the shell is as trusted as the boot chain, so any
+remaining way of reaching it is part of the boot chain. A console kept for
+diagnostics should be output-only.
+
 Disabling the non-builtin environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -156,6 +162,18 @@ 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.
 
+If environment handling is needed for other purposes, denying
+``SCONFIG_ENVIRONMENT_LOAD`` in the
+:ref:`security policy <use_security-policies>` keeps barebox from loading an
+environment from media.
+
+What matters is not the environment itself, but the global variables it sets.
+They select the boot source, end up on the kernel command line and, unless
+signature checking is pinned, decide whether images are verified at all. Any
+way to arbitrarily set global variables, be it a writable environment,
+a script on media or a shell, defeats verified boot regardless of how well
+the images are signed.
+
 Avoiding use of file systems
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
2.47.3

[PATCH 07/11] Documentation: security: document the barebox update attack surface

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

Any checks that generic barebox code currently does at update time are
meant to reduce the likelihood of bricking a board and not as a security
measure. Spell that out.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index a618c05b1102..b204e6df8d23 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -56,6 +56,17 @@ fusing for both HABv4 and AHAB.
    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.
 
+Any verified boot setup that doesn't ensure that barebox was correctly signed
+before execution is thus fundamentally flawed. A corollary to this is that
+it's not enough to restrict the ways that barebox can be updated: An attacker
+can often overwrite barebox without its knowledge, via physical access or
+after having booted into the OS. barebox's signature being validated by the
+previous boot stage is thus paramount.
+
+Specifically, the checks :ref:`barebox update <update>` performs on an image,
+e.g. that it targets the right board, exist to reduce the risk of bricking
+the board and can be skipped with ``-f``. They are not a security measure.
+
 Ensuring the barebox devicetree is verified
 -------------------------------------------
 
-- 
2.47.3

[PATCH 08/11] Documentation: security: update for barebox dm-verity support

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

We have gained dm-verity support in the meantime, so there is actually
something we can offer users that want to use file systems in a secure
manner, even though they will need to bring their own scheme on how to
discover the signed root hash.

Reflect this in the documentation.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index b204e6df8d23..185adac2d51c 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -190,14 +190,18 @@ Avoiding 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
+Especially, :ref:`bootloader spec files <bootloader_spec>` or
+:ref:`extlinux.conf <extlinux_conf>` 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.
+a file system and directly in a raw partition and not pointed at by a plain
+unsigned file on an unsigned file system that can both be tampered with.
+
+If file system use is desired anyway, its integrity should be ensured by
+other means, e.g. by being mounted from a dm-verity block device that was
+setup with a correctly signed root hash.
 
 Prevent the kernel from booting the rootfs in verity boots
 ----------------------------------------------------------
-- 
2.47.3

[PATCH 09/11] Documentation: security: add anchors for the different sections

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

So they can be referred to from the threat model chapter.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/security.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index 185adac2d51c..1ad4fa905d54 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -84,6 +84,8 @@ devicetree from the previous stage. It's thus only suitable for verified
 boot if that stage verified the devicetree as well, e.g. because both are
 part of the same signed FIP image.
 
+.. _loading_firmware:
+
 Loading firmware
 ----------------
 
@@ -97,6 +99,8 @@ Firmware) should happen as early as possible, i.e., within the barebox
 barebox will run with elevated permission, which greatly increases the attack
 surface.
 
+.. _pinning_fit_config:
+
 Pinning the FIT configuration
 -----------------------------
 
@@ -138,6 +142,8 @@ development keys into the barebox binary.
 The private keys for these keys can be found
 `[here] <https://github.com/pengutronix/ptx-code-signing-dev>`__.
 
+.. _disabling_shell:
+
 Disabling the shell
 ^^^^^^^^^^^^^^^^^^^
 
@@ -157,6 +163,8 @@ that. Whoever reaches the shell is as trusted as the boot chain, so any
 remaining way of reaching it is part of the boot chain. A console kept for
 diagnostics should be output-only.
 
+.. _disabling_env:
+
 Disabling the non-builtin environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -185,6 +193,8 @@ way to arbitrarily set global variables, be it a writable environment,
 a script on media or a shell, defeats verified boot regardless of how well
 the images are signed.
 
+.. _avoiding_filesystems:
+
 Avoiding use of file systems
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -203,6 +213,8 @@ If file system use is desired anyway, its integrity should be ensured by
 other means, e.g. by being mounted from a dm-verity block device that was
 setup with a correctly signed root hash.
 
+.. _verity_root_param:
+
 Prevent the kernel from booting the rootfs in verity boots
 ----------------------------------------------------------
 
@@ -248,6 +260,8 @@ 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.
 
+.. _runtime_configuration:
+
 Run-time configuration
 ^^^^^^^^^^^^^^^^^^^^^^
 
-- 
2.47.3

[PATCH 10/11] Documentation: define a barebox threat model

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

The security considerations chapter is written for integrators and
tells them what to configure.

Security researchers may not know how barebox is integrated, so let's
document what we count as a security vulnerability and what's a normal
bug.

The structure follows Linux's Documentation/process/threat-model.rst:
what barebox is responsible for, what it assumes about earlier boot
stages and the integrator, what it protects against when these
assumptions hold, and which problems are not vulnerabilities.

Security policies get their own section: a feature the active policy
denies can't be reached on a locked-down system, so a bug in it isn't
a vulnerability.

Assisted-by: Claude:fable-5.1
Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/threat-model.rst | 297 ++++++++++++++++++++++++++++
 Documentation/user/user-manual.rst  |   1 +
 2 files changed, 298 insertions(+)
 create mode 100644 Documentation/user/threat-model.rst

diff --git a/Documentation/user/threat-model.rst b/Documentation/user/threat-model.rst
new file mode 100644
index 000000000000..d15e1bda63b8
--- /dev/null
+++ b/Documentation/user/threat-model.rst
@@ -0,0 +1,297 @@
+.. _threat_model:
+
+The barebox threat model
+========================
+
+It is not necessarily self-explanatory what barebox does and does not protect
+against. This makes it hard to tell security bugs from ordinary ones, and to
+know who is responsible for what: barebox, the boot stages before it or the
+integrator who configures it.
+
+This document describes what barebox is responsible for, so that
+vulnerabilities can be told apart from ordinary bugs. For how to configure
+barebox securely, see :ref:`security`.
+
+barebox's responsibilities
+--------------------------
+
+barebox is one stage in a boot chain. In a verified boot chain, it must only
+start software it has verified, and only use configuration that the previous
+stage verified together with barebox itself.
+
+barebox trusts the previous boot stage and everything it verified as part of
+the barebox image. This includes the :ref:`prebootloader <pbl>`, barebox
+proper, the :ref:`internal devicetree <internal_devicetree>`, the built-in
+environment, the compiled-in public keys and security policies, and firmware
+like OP-TEE that the prebootloader installs at a higher privilege level. If
+any of these is left unverified, barebox can't make up for it.
+
+.. note::
+
+     The previous stage may verify only the prebootloader, as the i.MX8M boot
+     ROM does. The prebootloader then checks barebox proper and external
+     firmware against hashes built into it before using them to extend the
+     chain of trust.
+
+barebox also assumes that the hardware works as documented: the mask ROM
+verifies what it's documented to verify, fuses read back as programmed, the
+secure world stays isolated from the normal world and peripherals respect
+their documented register ranges. barebox doesn't currently defend against
+attacks on the hardware itself, like fault injection or side channels.
+
+Everything barebox reads at runtime is untrusted. This includes partition
+tables and file systems, boot images and boot entries, devicetree overlays,
+firmware and update images, environment or state on storage media and input
+from console, network or USB. Of these, barebox can only authenticate FIT
+images, HMAC-protected state, signed TLVs and JSON Web Tokens, and only if
+it is configured to require it.
+
+The integrator decides which of these inputs barebox uses at all and what it
+accepts from them: at build time via Kconfig and at runtime via security
+policies. barebox's defaults are made for convenient development, so a
+system is only locked down if it's configured that way; :ref:`security`
+describes how.
+
+Security policies
+^^^^^^^^^^^^^^^^^
+
+A :ref:`security policy <use_security-policies>` is a set of ``SCONFIG_``
+options compiled into barebox. Board code or ``CONFIG_SECURITY_POLICY_INIT``
+selects one at runtime. The active policy decides, among others, whether
+barebox may
+
+* read input from the console (``SCONFIG_CONSOLE_INPUT``) and
+  offer an interactive shell (``SCONFIG_SHELL_INTERACTIVE``),
+
+* load an environment from storage media (``SCONFIG_ENVIRONMENT_LOAD``),
+
+* mount file systems other than devfs and ramfs (``SCONFIG_FS_EXTERNAL``),
+
+* boot images without a valid signature (``SCONFIG_BOOT_UNSIGNED_IMAGES``),
+
+* be remote-controlled over RATP (``SCONFIG_RATP``), accept fastboot OEM
+  commands (``SCONFIG_FASTBOOT_CMD_OEM``) or act as a USB gadget at all
+  (``SCONFIG_USB_GADGET``).
+
+A locked-down system should deny all of these by default and allow them only
+after authentication, e.g. with a device-bound unlock token as described in
+:ref:`Run-time configuration <runtime_configuration>`. A bug in a denied
+feature then can't be reached. Before reporting a bug in one of these
+features as a vulnerability, check whether it can still be reached with the
+feature denied. A way to get around the policy and use a denied feature is a
+vulnerability.
+
+Protections
+^^^^^^^^^^^
+
+If the `Assumptions`_ below hold, barebox guarantees the following:
+
+* **Verified hand-over**: barebox only starts or passes on what a trusted key
+  has signed: the kernel, initramfs, devicetree, overlays and firmware in a
+  FIT image whose configuration signature was verified, with
+  :ref:`global.bootm.verify <magicvar_global_bootm_verify>` pinned to
+  ``signature``.
+
+* **Verified configuration**: the verified image, not untrusted input,
+  decides what barebox boots, what it tells the kernel and whether it
+  verifies images. The only exception is where the configuration explicitly
+  leaves a choice open, like which of a FIT's signed configurations to boot.
+
+* **Memory safety against untrusted input**: parsing untrusted input necessary
+  for booting from storage media or the console doesn't corrupt memory, so an
+  attacker can't use it to run their own code.
+
+* **Policy enforcement**: a feature the active security policy denies can't
+  be used.
+
+A bug that breaks one of these guarantees is a vulnerability. A bug that can
+only be exploited after another guarantee is already broken is just a
+weakness. barebox also has hardening measures that keep some classes of bugs
+from crossing a security boundary, but a failure of these extra protections
+alone is not a vulnerability.
+
+Assumptions
+-----------
+
+barebox relies on the integrator to ensure the following. barebox can't
+check them, and if one doesn't hold, no barebox configuration can make up
+for it.
+
+**barebox is authenticated before it is executed**
+   An earlier stage (the mask ROM or another bootloader, like ARM Trusted
+   Firmware) verifies the barebox image, and the board is locked down so an
+   unverified barebox won't run. Restricting who may update barebox is only
+   defence in depth.
+
+**The devicetree is authenticated together with barebox**
+   Keys under ``/signature`` in the internal devicetree are trusted just like
+   compiled-in keys and can sign any FIT configuration. So whoever controls
+   the devicetree controls what barebox accepts. The devicetree must be built
+   into the barebox image or come from a stage that verified it, e.g. ARM
+   Trusted Firmware loading it from a verified FIP.
+
+**Only the built-in environment configures barebox**
+   Global variables decide what is booted, what the kernel is told and,
+   unless signature checking is pinned, whether images are verified at all.
+   The environment sets these variables, so only the environment built into
+   the verified image may be used; see
+   :ref:`Disabling the non-builtin environment <disabling_env>`.
+
+**Only authorized users reach the shell**
+   The shell is the administrative interface. It can be reached over a
+   serial console, the :ref:`network console <network_console>`, the RATP
+   protocol used by bbremote, or fastboot, whose ``oem exec`` command is as
+   powerful as the shell. Commands that write a partition, set a variable or
+   apply an overlay do so without further checks.
+   See :ref:`Disabling the shell <disabling_shell>` for more information.
+
+**Files barebox is told to load reside in trusted storage**
+   Some data is only referenced by name, not included. For example, a
+   devicetree overlay in a signed FIT may have an ``fpga-region`` node with a
+   ``firmware-name`` property. barebox loads that file from
+   ``global.firmware.path`` and programs it into the FPGA. The signature
+   covers the name, not the file, so such paths must point at trusted
+   storage, e.g. the built-in environment or a file system protected by other
+   means, like dm-verity with a signed root hash.
+
+**barebox is configured securely**
+   Beyond the above, barebox must be configured securely at build time via
+   Kconfig and at runtime via
+   :ref:`security policies <use_security-policies>`, as described in
+   :ref:`security`. A bug that only affects a configuration that chapter
+   advises against isn't a vulnerability.
+
+What classes of problems are not considered vulnerabilities
+-----------------------------------------------------------
+
+The following classes of problems are **not** considered barebox
+vulnerabilities. They should still be reported where barebox could do
+better, so they can be fixed where reasonably possible, but they are handled
+like any regular bug:
+
+* **Configuration**:
+
+  * outdated versions: integrators must keep barebox up to date. A
+    vulnerability must be shown to affect the latest release or one of the
+    long term stable releases listed in ``SECURITY.md``.
+
+  * build-level: builds that lack the verification they rely on, e.g.
+    ``CONFIG_BOOTM_FITIMAGE`` without ``CONFIG_BOOTM_FITIMAGE_SIGNATURE``, or
+    with a security policy denying something the build can't enforce. Also
+    options documented as lowering security, in particular everything
+    ``CONFIG_INSECURE`` enables, and code that only exists for development or
+    debugging, like the sandbox architecture's host interfaces, fuzzing
+    harnesses or development keys.
+
+  * runtime-level: a security policy that was configured to allow what should
+    be denied in a verified boot setup, e.g. ``SCONFIG_BOOT_UNSIGNED_IMAGES``
+    or ``SCONFIG_SHELL_INTERACTIVE`` in a lockdown policy, or no policy selected
+    at all on a build that then permits everything
+    (``CONFIG_SECURITY_POLICY_DEFAULT_PERMISSIVE``). Also
+    :ref:`global.bootm.verify <magicvar_global_bootm_verify>` set to anything
+    but ``signature``, or not pinned to it.
+
+  * a barebox image, devicetree or environment the previous boot stage
+    didn't authenticate; see `Assumptions`_.
+
+  * barebox proper running in the secure world, because OP-TEE isn't
+    started from the prebootloader; see :ref:`loading_firmware`.
+
+  * boot entries referencing a FIT:
+    :ref:`bootloader spec <bootloader_spec>` entries and
+    :ref:`extlinux.conf <extlinux_conf>` files come from a file system
+    barebox can't verify. Pointing them at a signed FIT doesn't make the boot
+    trustworthy; see
+    :ref:`Avoiding use of file systems <avoiding_filesystems>`.
+
+* **Excess of initial privileges**:
+
+  Anything an attacker can do if they already have the access it requires:
+
+  * an image with a signature barebox accepts. Whoever can create one
+    already has the signing key, so a bug that can only be reached this way
+    doesn't bypass verification.
+
+  * anything done from the shell or via a global variable set from a loaded
+    environment.
+
+  * anything that follows from controlling the devicetree, which carries
+    the keys.
+
+  * anything done through a feature the active security policy allows, e.g.
+    flashing a partition via fastboot on a system whose policy permits
+    fastboot OEM commands.
+
+  * a bug in the barebox environment parser:
+    The environment can contain scripts, and there is no way to sign an
+    environment that isn't built in. An attacker can just add an init
+    script instead of attacking the parser.
+
+  * a bug in an unsigned kernel image format:
+    Kernel images should be placed in a signed container. An attacker who
+    can modify a kernel image without breaking a signature can simply make
+    it run their own code once barebox starts it. There is no need to attack
+    the kernel header barebox parses.
+
+  * a bug in a feature that the documentation calls
+    unsuitable for verified boot and that can be disabled at build time or
+    runtime, but wasn't.
+    For an example, see
+    :ref:`avoiding use of file systems <avoiding_filesystems>`.
+
+* **Selecting among signed configurations**:
+
+  A FIT signature covers the configuration it's in, but not the ``default``
+  property that picks a configuration when barebox isn't told which one to
+  boot. Booting a different signed configuration of the same FIT is
+  therefore not a bypass; see :ref:`pinning_fit_config`.
+
+* **Update images**:
+
+  :ref:`barebox_update <update>` and fastboot's ``flash`` command don't
+  authenticate anything. Their checks, e.g. that the image is for the right
+  board, only exist to avoid bricking the board. The previous boot stage,
+  not barebox, verifies what gets installed.
+
+* **Network boot**:
+
+  The network isn't meant to be used in verified boot setups, and booting
+  over it is not a verified boot path. DHCP options, the hostname and files
+  fetched via TFTP or NFS are as untrusted as any other input and the barebox
+  network stack implementation is not hardened against adversaries.
+
+* **Denial of service by way of a boot image**:
+
+  barebox tries to reject malformed images, but an image that makes barebox
+  hang, panic or refuse to boot isn't a vulnerability: whoever can supply
+  such an image can just as well prevent booting by erasing it. Memory
+  corruption is still in scope, as it can let an attacker run their own
+  code.
+
+* **Hardening failures**:
+
+  * a missing bounds or argument check whose only effect is that a
+    malformed image is rejected later than it could have been.
+
+  * bypassing a defence in depth measure without showing how to exploit it
+    further.
+
+* **Random information leaks**:
+
+  Small amounts of memory the attacker can't choose reaching the console,
+  e.g. through unterminated strings, structure padding or printed memory
+  addresses.
+
+* **Physical access**:
+
+  A verified boot chain is meant to hold up even when the attacker has the
+  device in hand. So everything barebox reads over its external interfaces
+  (storage media, USB and the serial console) is in scope, no matter how the
+  attacker got access. Attacks that bypass or modify the hardware are out of
+  scope: fault injection, debug ports like JTAG that the integrator should have
+  fused off, or replacing the storage barebox itself is loaded from, which the
+  previous boot stage must detect.
+
+Report vulnerabilities to security@barebox.org as described in
+``SECURITY.md``. Everything else is welcome on the mailing list; see
+:ref:`feedback`.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index b312f60e8187..296422475bbd 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -30,6 +30,7 @@ Contents:
    devboot
    bootchooser
    remote-control
+   threat-model
    security
    security-policies
    reset-reason
-- 
2.47.3

[PATCH 11/11] README, SECURITY.md: link the threat model and security considerations

[Ahmad Fatoum]

From: Ahmad Fatoum <a.fatoum@barebox.org>

SECURITY.md says where to report vulnerabilities, but not what counts as
one. The README says nothing about security.

Link the new threat model from both files. In the README, add a short
Security section that also links the Security Considerations chapter.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 README.rst  | 10 ++++++++++
 SECURITY.md |  6 ++++++
 2 files changed, 16 insertions(+)

diff --git a/README.rst b/README.rst
index fe783028dfad..1800f5e51822 100644
--- a/README.rst
+++ b/README.rst
@@ -284,6 +284,16 @@ are the release rules:
   does never change, in order to make life easier for distribution
   people.
 
+Security
+--------
+
+The `threat model <https://www.barebox.org/doc/latest/user/threat-model.html>`_
+describes what barebox does and does not protect against and which bugs are
+considered security vulnerabilities. The
+`Security Considerations <https://www.barebox.org/doc/latest/user/security.html>`_
+chapter describes how to configure barebox for verified boot. Refer to
+``SECURITY.md`` for how to report vulnerabilities.
+
 .. _contributing:
 
 Contributing
diff --git a/SECURITY.md b/SECURITY.md
index 862dd14623d9..39407514a361 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -19,7 +19,13 @@ releases:
 Please report security vulnerabilities to security@barebox.org.
 We will work with the reporter to create a fix and to coordinate the disclosure.
 
+The [threat model](https://www.barebox.org/doc/latest/user/threat-model.html)
+describes what barebox does and does not protect against and which classes of
+bugs are not vulnerabilities. Report those as ordinary bugs on the
+[mailing list](https://www.barebox.org/doc/latest/user/introduction.html#feedback).
+
 ## Securing barebox
 
 Refer to the [Security Considerations](https://www.barebox.org/doc/latest/user/security.html)
 chapter of the documentation for information on how to configure barebox securely.
+That advice relies on the assumptions listed in the threat model.
-- 
2.47.3