[PATCH 09/24] docs: security-policies: add documentation
Sascha Hauer
s.hauer at pengutronix.de
Wed Aug 20 06:17:53 PDT 2025
From: Ahmad Fatoum <a.fatoum at barebox.org>
Let's add some first documentation for the newly added security policy
support.
Signed-off-by: Ahmad Fatoum <a.fatoum at pengutronix.de>
---
Documentation/devel/devel.rst | 1 +
Documentation/devel/security-policies.rst | 96 ++++++++++++++++++++++++
Documentation/user/security-policies.rst | 121 ++++++++++++++++++++++++++++++
Documentation/user/user-manual.rst | 1 +
Makefile | 2 +-
security/Kconfig.policy | 4 +-
6 files changed, 222 insertions(+), 3 deletions(-)
diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst
index b90805263bbd669891979b3323ba3797b4e191b1..84074d142e031ef7bde515151e2d513d215f3293 100644
--- a/Documentation/devel/devel.rst
+++ b/Documentation/devel/devel.rst
@@ -13,6 +13,7 @@ Contents:
troubleshooting
filesystems
background-execution
+ security-policies
project-ideas
fuzzing
diff --git a/Documentation/devel/security-policies.rst b/Documentation/devel/security-policies.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8d0b5e7fde37f1893b8ddb8acd29f7eed9fc5a6c
--- /dev/null
+++ b/Documentation/devel/security-policies.rst
@@ -0,0 +1,96 @@
+.. _develop_security-policies:
+
+Security Policies (Developer Manual)
+====================================
+
+Overview
+--------
+
+This document describes how to define new SConfig symbols and integrate them
+into Barebox security policies. SConfig uses the same backend as Kconfig, and
+its configuration files live alongside Kconfig files (e.g. ``common/Sconfig``).
+
+Key principles:
+
+- Except for the name, symbols are always ``bool``.
+- Policies are board-specific and described in ``.sconfig`` files at build-time.
+- Every policy is complete and no implicit defaults are applied by mere building
+- Policy ``.sconfig`` files are post-processed into ``.sconfig.c`` files and
+ then compiled and linked into the final barebox binary.
+
+Creating New Symbols
+--------------------
+
+1. **Add a new symbol** to the appropriate ``Sconfig`` file, such as ``common/Sconfig``:
+
+ .. code-block:: kconfig
+
+ config ENV_HANDLING
+ bool "Allow persisting and loading the environment from storage"
+ depends on $(kconfig-enabled ENV_HANDLING)
+
+2. **Reference it in code** using:
+
+ .. code-block:: c
+
+ #include <security/config.h>
+
+ if (!IS_ALLOWED(SCONFIG_ENV_HANDLING))
+ return -EPERM;
+
+3. **Update policies**:
+
+ Every existing ``.sconfig`` policy must define a value for the new symbol
+ as there are no implicit defaults to ensure every policy explicitly encodes
+ all options in accordance with its security requirements.
+
+ Example in ``myboard-lockdown.sconfig``:
+
+ .. code-block:: none
+
+ SCONFIG_ENV_HANDLING=n
+
+ And in ``myboard-devel.sconfig``:
+
+ .. code-block:: none
+
+ SCONFIG_ENV_HANDLING=y
+
+Linking Policy Files
+--------------------
+
+Policies can be added to the build using ``policy-y`` in the board’s
+Makefile:
+
+.. code-block:: make
+
+ policy-y += myboard-lockdown.sconfig
+
+As policies are enforced to be complete, they may require resynchronization
+(e.g., with ``make olddefconfig``) if the config changes. A build failure
+will alert the user to this fact.
+
+``virt32_secure_defconfig`` is maintained as reference configuration for
+trying out security policies and that it's buildable is ensured by CI.
+
+Tips for Symbol Design
+----------------------
+
+- Avoid naming symbols after board names. Favor functionality.
+- Prefer giving Sconfig symbols the same name as Kconfig symbols, when they
+ address the same goal, but at runtime instead of build-time.
+- When possible, reuse logic in core code by wrapping around
+ ``IS_ALLOWED()`` checks.
+
+Validation & Maintenance
+------------------------
+
+Always run ``make security_olddconfig`` for the security policy reference
+configuration ``virt32_policy_defconfig``::
+
+ export ARCH=arm
+ export CROSS_COMPILE=...
+ make virt32_policy_defconfig
+ make security_olddefconfig
+
+CI also checks this configuration and verifies that it's up-to-date.
diff --git a/Documentation/user/security-policies.rst b/Documentation/user/security-policies.rst
new file mode 100644
index 0000000000000000000000000000000000000000..94b470ee693deb0688b0d61128f5257fa412e403
--- /dev/null
+++ b/Documentation/user/security-policies.rst
@@ -0,0 +1,121 @@
+.. _use_security-policies:
+
+Security Policies (User Manual)
+===============================
+
+Overview
+--------
+
+Barebox supports structured security configuration through **security policies**,
+a runtime configuration mechanism that allows switching between multiple
+predefined security policies (e.g. ``lockdown``, ``devel``),
+depending on operational requirements.
+
+This replaces ad-hoc board code with a clean, reproducible, and
+auditable configuration-based model.
+
+Concepts
+--------
+
+- **SConfig**: A configuration system using the same backend as
+ Kconfig, designed for **runtime security policies**.
+- **Policies**: Named configurations like ``myboard-lockdown.sconfig``,
+ ``myboard-open.sconfig`` specific to each board.
+
+Usage
+-----
+
+1. **Configure a policy** using menuconfig (or another frontend):
+
+ .. code-block:: shell
+
+ make KPOLICY=arch/arm/boards/myboard/myboard-lockdown.sconfig security_oldconfig
+ make security_menuconfig # Iterates over all policies
+
+2. **Configuration files** (e.g. ``myboard-lockdown.sconfig``) are in Kconfig
+ format with ``SCONFIG_``-prefixed entries.
+
+3. **Build integration**:
+
+ The sconfig files for the board are placed into the ``security/``
+ directory in the source tree and their relative file names
+ (i.e., with the ``security/`` prefix) are added to
+ ``CONFIG_SECURITY_POLICY_PATH``.
+
+ Alternatively, policies can also be be referenced in a board's
+ Makefile::
+
+ .. code-block:: make
+
+ lwl-y += lowlevel.o
+ obj-y += board.o
+ policy-y += myboard-lockdown.sconfig myboard-devel.sconfig
+
+ This latter method can be useful when building multiple boards in
+ the same build, but with different security policies.
+
+4. **Registration**:
+
+ Policies added with ``CONFIG_SECURITY_POLICY_PATH`` are automatically
+ registered for all enabled boards.
+
+ Policies added with policy-y need to be explicitly added by symbol
+ to the set of registered policies in board code:
+
+ .. code-block:: c
+
+ #include <security/policy.h>
+
+ security_policy_add(myboard_lockdown)
+ security_policy_add(myboard_devel)
+
+5. **Runtime selection**:
+
+ In board code, switch to a policy by name:
+
+ .. code-block:: c
+
+ #include <security/policy.h>
+
+ security_policy_select("lockdown");
+
+Trying it out
+-------------
+
+``virt32_secure_defconfig`` is the current reference platform for security
+policy development and evaluation. ``images/barebox-dt-2nd.img`` that results
+from building it can be passed as argument to ``qemu-system-arm -M virt -kernel``.
+
+The easiest way to do this is proabably installing labgrid and running
+``pytest --interactive`` after having built the config.
+
+Differences from Kconfig
+------------------------
+
++-------------------------+------------------------------+-----------------------------+
+| Feature | Kconfig | SConfig |
++=========================+==============================+=============================+
+| Purpose | Build-time configuration | Runtime security policy |
++-------------------------+------------------------------+-----------------------------+
+| File name | .config | ${policy}.sconfig |
++-------------------------+------------------------------+-----------------------------+
+| policies per build | One | Multiple |
++-------------------------+------------------------------+-----------------------------+
+| Symbol types | bool, int, string, ... etc. | bool only |
++-------------------------+------------------------------+-----------------------------+
+| Symbol dependencies | Kconfig symbols | Both Kconfig and Sconfig |
+| | | symbols |
++-------------------------+------------------------------+-----------------------------+
+
+Best Practices
+--------------
+
+- Maintain all ``.sconfig`` files under version control,
+ either as part of the barebox patch stack or in your BSP
+
+- Document reasoning when changing every single security option
+ (even when doing ``security_olddefconfig``).
+
+- Avoid logic duplication in board code — rely on SConfig conditionals.
+
+- Name policies meaningfully: e.g. ``lockdown``, ``tamper``, ``return``.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index ce0792000a3ce68aa3b9dd2ce685ef7b0f40a2d5..cb01721863ddfb133e331487ebb1c6206e4d704c 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -29,6 +29,7 @@ Contents:
bootchooser
remote-control
security
+ security-policies
reset-reason
system-reset
state
diff --git a/Makefile b/Makefile
index 6027b5c37c82a99d1e9518edb790e9934378afab..49658e5fe28f913e4c12b9dd5b52fb91cc19a79a 100644
--- a/Makefile
+++ b/Makefile
@@ -1215,7 +1215,7 @@ security_%config: collect-policies $(KPOLICY.tmp) FORCE
$(@:security_%=%),$p.tmp))
ifeq ($(KPOLICY_TMPUPDATE),)
+$(Q)$(foreach p, $(KPOLICY), \
- cp 2>/dev/null $p.tmp $(call resolve-srctree,$p) || true;)
+ cp 2>/dev/null $p.tmp $(call resolve-srctree,$p);)
endif
quiet_cmd_sconfigpost = SCONFPP $@
diff --git a/security/Kconfig.policy b/security/Kconfig.policy
index bf938a9f3dd87fc21009f0260f3cf8be7937bd36..afe1c17735edd4387c6b0b88b0429c51ea52dcac 100644
--- a/security/Kconfig.policy
+++ b/security/Kconfig.policy
@@ -54,11 +54,11 @@ config SECURITY_POLICY_INIT
the restrictions if needed instead of the other way round.
choice
- prompt "Initial Security Policy"
+ prompt "Behavior on missing security policy"
default SECURITY_POLICY_DEFAULT_PERMISSIVE
config SECURITY_POLICY_DEFAULT_PERMISSIVE
- bool "Permissive by default"
+ bool "Permissive"
select HAS_INSECURE_DEFAULTS
help
In absence of a selected security policy, everything is allowed.
--
2.39.5
More information about the barebox
mailing list