From: Ahmad Fatoum <a.fat...@barebox.org>
Let's add some first documentation for the newly added security policy
support.
Signed-off-by: Ahmad Fatoum <a.fat...@pengutronix.de>
---
Documentation/devel/devel.rst | 1 +
Documentation/devel/security-policies.rst | 96 ++++++++++++++++++++++
Documentation/user/security-policies.rst | 131 ++++++++++++++++++++++++++++++
Documentation/user/user-manual.rst | 1 +
4 files changed, 229 insertions(+)
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..ba458b10b34bb75ab817c6e1a97272ea7463e37e
--- /dev/null
+++ b/Documentation/user/security-policies.rst
@@ -0,0 +1,131 @@
+.. _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");
+
+Limitations
+-----------
+
+Always start with the most restrictive policy and switch to more permissive
policies later
+when needed. Forbidding previously allowed options might have undesired side
effects which
+include:
+
+- Forbidding mounting of file systems does not affect already mounted file
systems
+- Forbidding shell does not affect the already running instance
+
+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
--
2.47.3
