[PATCH 09/24] docs: security-policies: add documentation

[Sascha Hauer <s.hauer@pengutronix.de>]

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

Let's add some first documentation for the newly added security policy
support.

Signed-off-by: Ahmad Fatoum <a.fatoum@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