From: Ahmad Fatoum <[email protected]> Let's add some first documentation for the newly added security policy support.
Signed-off-by: Ahmad Fatoum <[email protected]> --- 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
