.. _os-security-architecture:

#################################
OrchestraOS Security Architecture
#################################

Security behavior depends on the target, image features, signing material, and
device provisioning state. Building signed artifacts and enforcing their
authentication on a device are separate operations.

.. list-table:: Security mechanisms and conditions
   :header-rows: 1
   :widths: 24 38 38

   * - Mechanism
     - Implementation
     - Conditions and scope
   * - Authenticated boot on EIG hardware
     - HAB4 on i.MX8M targets; AHAB on EIGXS/i.MX93. The BSP builds signed
       bootloader and kernel artifacts when the signing features are selected.
     - Enforcement requires matching device trust anchors and the appropriate
       secure lifecycle state. Reference signing keys must be replaced for a
       production deployment.
   * - ARM Trusted Firmware and OP-TEE
     - Board-specific secure firmware and trusted services are integrated by
       the BSP.
     - Available services and their use depend on the SoC and selected
       software. Presence of a TEE does not automatically protect application
       secrets.
   * - Encrypted persistent storage
     - The optional crypt layer unlocks an encrypted LVM device in initramfs.
     - Protects rootfs A/B, application A/B, and data. Boot filesystems and the
       provisioning partition remain outside encrypted LVM. See
       :ref:`os-extended-security`.
   * - TPM2 interfaces
     - TPM2 tools, PKCS#11 support, resource-manager software, and Python
       bindings are included by the reference package policy.
     - A usable TPM, matching device tree, and application provisioning are
       required. Installed packages alone do not establish key ownership.
   * - Signed system updates
     - RAUC verifies bundles against the image's configured certificate
       keyring; the reference bundle format is ``verity``.
     - Bundle signing and boot authentication have separate trust material.
       Replace the RAUC development certificate and signing key as well as the
       platform boot-signing keys.
   * - Read-only root filesystem
     - Common images request ``read-only-rootfs``. Rootfs-on-LVM images use
       ``overlayfs-etc`` backed by ``/data``.
     - Persistent configuration and application state remain writable. A
       read-only mount is not a cryptographic integrity guarantee.

Boot Artifact Policy
====================

Signed EIG configurations use the authenticated kernel boot payload selected by
the BSP. The U-Boot environment defines slot selection and the boot partition
contains the corresponding boot artifacts.

EIGXS authenticates an AHAB OS container containing the kernel, device tree,
and separate initramfs. HAB4 targets use their platform signing flow. See
:ref:`os-booting-process-nxp` and :ref:`os-signing-keys` for the packaging and
provisioning boundaries.

The QEMU UEFI configuration provides EFI boot and RAUC slot selection. Its
use of UEFI does not establish UEFI Secure Boot signing or key enrollment.
The EIG hardware fuse procedures do not apply to QEMU.

Access and Application Integration
==================================

The reference ``ct`` account has passwordless sudo and membership in device and
Docker groups. SSH authentication depends on the image variant. These are
development defaults to review as part of a deployment's access policy; see
:ref:`os-runtime-access`.

Enrollment, remote command policy, and the device credential lifecycle are
supplied by the selected Orchestra Manager Platform integration. See
:ref:`os-runtime-services` for its device-side requirements.

Build-time vulnerability reports describe the selected software and database
snapshot. They do not certify the security of a deployed system. Report formats
and configuration are described in :ref:`os-sbom`.