From 68042e23c89d52c0dfb2d65153f2ddd1ac8ffb61 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Thu, 11 Jun 2026 11:08:13 +0200 Subject: [PATCH 01/13] rauc: walnascar: Add reference Signed-off-by: Leonard Anderweit --- source/rauc/walnascar.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/rauc/walnascar.rst b/source/rauc/walnascar.rst index 7c2985b37..4bbcceaf3 100644 --- a/source/rauc/walnascar.rst +++ b/source/rauc/walnascar.rst @@ -29,6 +29,8 @@ This manual was tested using the Yocto version |yocto-codename|. +.. _rauc-man-walnascar: + .. include:: common/intro.rsti .. include:: common/system-config.rsti .. include:: common/design-considerations.rsti From b4d7f957136e1bf957a3a4fbc443a018dd3883c7 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Tue, 19 May 2026 11:54:56 +0200 Subject: [PATCH 02/13] security: Rebrand to securiPHY Rebrand from SECURIphy to securiPHY. Signed-off-by: Leonard Anderweit --- source/security/common/security-overview.rsti | 4 ++-- source/security/head-sec.rst | 2 +- source/security/scarthgap-sec.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/security/common/security-overview.rsti b/source/security/common/security-overview.rsti index 1d0930cc5..00f9200a9 100644 --- a/source/security/common/security-overview.rsti +++ b/source/security/common/security-overview.rsti @@ -1,7 +1,7 @@ -SECURIphy Overview +SecuriPHY Overview ================== -SECURIphy is the PHYTEC secure linux distribution and a part of the security +SecuriPHY is the PHYTEC secure linux distribution and a part of the security packages phyKNOX. .. image:: images/phyknox-packages.png diff --git a/source/security/head-sec.rst b/source/security/head-sec.rst index 6920e8d3d..a3e478a19 100644 --- a/source/security/head-sec.rst +++ b/source/security/head-sec.rst @@ -7,7 +7,7 @@ .. |phytec-pki-link| replace:: :ref:`phytec-pki-head` .. Yocto -.. |branding-name| replace:: SECURIphy +.. |branding-name| replace:: securiPHY .. |yocto-codename| replace:: Walnascar .. |distro-secure-vendor| replace:: securiphy-vendor .. |distro-secure| replace:: securiphy diff --git a/source/security/scarthgap-sec.rst b/source/security/scarthgap-sec.rst index 4b47100f8..caecefe48 100644 --- a/source/security/scarthgap-sec.rst +++ b/source/security/scarthgap-sec.rst @@ -7,7 +7,7 @@ .. |physical-security-link| replace:: :ref:`physical-security-scarthgap` .. Yocto -.. |branding-name| replace:: SECURIphy +.. |branding-name| replace:: securiPHY .. |yocto-codename| replace:: Scarthgap .. |distro-secure-vendor| replace:: securiphy-vendor .. |distro-secure| replace:: securiphy @@ -66,7 +66,7 @@ This manual applies to all |yocto-codename| based PHYTEC releases. Introduction ============ -PHYTEC's Yocto distribution Securiphy (former Ampliphy-secure) supports +PHYTEC's Yocto distribution securiPHY (former Ampliphy-secure) supports different security mechanism. The security features have impact on the bootloader, the Linux kernel, Device Tree, and root filesystem. This manual describes how security features are used and implemented on various PHYTEC From ca51d4519f6abc68cb104ca6d1a21a0c1514403f Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Thu, 23 Apr 2026 09:45:38 +0200 Subject: [PATCH 03/13] security: activate-secureboot: move reset Reset the board before reading the fuses because 'fuse read' returns zeros instead of the programmed values before the reset. Signed-off-by: Leonard Anderweit --- source/security/common/activate-secureboot.rsti | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/security/common/activate-secureboot.rsti b/source/security/common/activate-secureboot.rsti index 93cfe0db1..c87ea635d 100644 --- a/source/security/common/activate-secureboot.rsti +++ b/source/security/common/activate-secureboot.rsti @@ -157,13 +157,13 @@ Burn the SRK || || ``u-boot=> fuse prog 7 2 0x704e9fe4`` || ``u-boot=> fuse prog 16 6 0xa541dfbe`` | || || ``u-boot=> fuse prog 7 3 0x9b025359`` || ``u-boot=> fuse prog 16 7 0x6ea06dba`` | +--------------------------------------------+--------------------------------------------------+--------------------------------------------------+ + | reset the board | ``u-boot=> reset`` | ``u-boot=> reset`` | + +--------------------------------------------+--------------------------------------------------+--------------------------------------------------+ || read and check || ``u-boot=> fuse read 6 0 4`` || ``u-boot=> fuse read 16 0 8`` | || the fuses || 0x00000000: 9a842534 b0491ab4 d5b6a07b fd92dce7 || 0x00000000: baaf5d2c e92e0323 23c0ba08 10e7973f | || || ``u-boot=> fuse read 7 0 4`` || 0x00000004: 678de0d5 966d3584 a541dfbe 6ea06dba | || || 0x00000000: c10dc87c d8bd04a9 704e9fe4 9b025359 || | +--------------------------------------------+--------------------------------------------------+--------------------------------------------------+ - | reset the booard | ``u-boot=> reset`` | ``u-boot=> reset`` | - +--------------------------------------------+--------------------------------------------------+--------------------------------------------------+ || check the state || ``u-boot=> hab_status`` || ``u-boot=> ahab_status`` | || || || Lifecycle: 0x00000008, OEM Open | || || No Events Found! || No Events Found! | From b92b3ebfd2005846f35c41577a8be276565a4718 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Thu, 23 Apr 2026 09:51:41 +0200 Subject: [PATCH 04/13] security: activate-secureboot: Remove unrelated content Activating the eMMC boot partitions manually is not necessary because takes care of that during provisioning. Signed-off-by: Leonard Anderweit --- .../security/common/activate-secureboot.rsti | 43 ------------------- 1 file changed, 43 deletions(-) diff --git a/source/security/common/activate-secureboot.rsti b/source/security/common/activate-secureboot.rsti index c87ea635d..013bff79d 100644 --- a/source/security/common/activate-secureboot.rsti +++ b/source/security/common/activate-secureboot.rsti @@ -1,9 +1,6 @@ Activate Secure Boot on the Device ================================== -The final step to activate Secure Boot on your device is to burn the secure -eFuse configuration. - .. warning:: The secure eFuse configuration can only be written once and is irreversible! @@ -18,46 +15,6 @@ stores these development keys to ``yocto/phytec-dev-ca`` Burn the right key into the Controller eFuse. Please refer to the chapter |secure-key-storage-link| -eMMC Boot Partition to Enable Boot ----------------------------------- - -If you install your eMMC with the partup image, then the eMMC is configured -with the right configuration. -If you install the bootloader standalone on the eMMC, then please check the -eMMC configuration for the -right partition. - -+------------------------------+---------------------------------+-----------------------------------+ -| | barebox | u-boot | -+==============================+=================================+===================================+ -| Set eMMC as an active device | ``barebox$ detect mmc3`` | ``u-boot=> mmc dev 2`` | -+------------------------------+---------------------------------+-----------------------------------+ -| Show active boot partition | ``barebox$ devinfo mmc3`` | ``u-boot=> mmc partconf 2`` | -+------------------------------+---------------------------------+-----------------------------------+ -| Set user area for boot | ``barebox$ mmc3.boot=disabled`` | ``u-boot=> mmc partconf 2 0 7 0`` | -+------------------------------+---------------------------------+-----------------------------------+ -| || disabled: user partition || 0x7: user partition | -| || boot0: Boot partition 0 || 0x1: Boot partition 0 | -| || boot1: Boot partition 1 || 0x2: Boot partition 1 | -+------------------------------+---------------------------------+-----------------------------------+ - -Active boot output for barebox: - .. code-block:: - - ... - Parameters: - boot: disabled (type: enum) (values: "disabled", "boot0", "boot1", "user") - nt_signature: 9a54880c (type: uint32) - probe: 0 (type: bool) - -Active boot output for u-boot - .. code-block:: - - EXT_CSD[179], PARTITION_CONFIG: - BOOT_ACK: 0x0 - BOOT_PARTITION_ENABLE: 0x1 - PARTITION_ACCESS: 0x7 - Activate Secure Boot for NXP SoC -------------------------------- From d4a657a3049a2a9961eb514174c2f90c04220944 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Fri, 24 Apr 2026 14:54:07 +0200 Subject: [PATCH 05/13] security: phytec-pki: Reduce information on phytec-dev-ca Remove information on phytec-dev-ca which is already present in the phytec-dev-ca repository. Signed-off-by: Leonard Anderweit --- source/security/common/phytec-pki.rsti | 34 -------------------------- 1 file changed, 34 deletions(-) diff --git a/source/security/common/phytec-pki.rsti b/source/security/common/phytec-pki.rsti index 255ea1465..6c5bcc0ce 100644 --- a/source/security/common/phytec-pki.rsti +++ b/source/security/common/phytec-pki.rsti @@ -30,40 +30,6 @@ the PHYTEC development keys are downloaded from They are used to sign the bootloader, FIT-image, Kernel modules, and the RAUC bundles. -+--------------------+-------------------------------------------------------+------------+ -| Name | Description | Key Type | -+====================+=======================================================+============+ -| main-ca | self-signed Certificate Authority | RSA-4096 | -+--------------------+-------------------------------------------------------+------------+ -| nxp_ahab_pki | NXP HABv4 Key Authority for i.MX93 | NIST P-521 | -+--------------------+-------------------------------------------------------+------------+ -|| nxp_habv4_pki || NXP HABv4 Key Authority for i.MX6/UL/ULL and || RSA-4096 | -|| || i.MX8M Nano/Mini/Plus || | -+--------------------+-------------------------------------------------------+------------+ -| ti_k3 | TI K3 Key Authority for AM62 / AM64 / AM68 | RSA-4096 | -+--------------------+-------------------------------------------------------+------------+ -| fit | Kernel FIT-image signing key and certificate | RSA-4096 | -+--------------------+-------------------------------------------------------+------------+ -|| kernel-modsign || Key for the Linux kernel module signing facility, || RSA-4096 | -|| || independent of CA || | -+--------------------+-------------------------------------------------------+------------+ -|| rauc-intermediate || RAUC CA (intermediate CA) and || RSA-2048 | -|| || RAUC CA sign development key for signing the bundles || | -+--------------------+-------------------------------------------------------+------------+ -|| rauc-intermediate || RAUC CA for device certificates to encrypt || RSA-4096 | -|| -crypt || update bundles || | -+--------------------+-------------------------------------------------------+------------+ - -The SoC specific nxp_ahab_pki, nxp_habv4_pki and ti_k3 are for signing the boot -container files, -which are verified with the SoC internal unit and SoC rom loader or dedicated -controllers in the SoC. - -All keys and certificates are stored in an XCA database phytec-dev-ca.xdb, -which can be configured with the open-source application XCA from -``_. -The password for the phytec-dev-ca.xdb is: phytec-dev-ca - Only the necessary keys and certificates for the build process are exported to the directory. From 0da47424cdda61a27d2e7bdba5f966f54f30bfa4 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Wed, 27 May 2026 13:34:09 +0200 Subject: [PATCH 06/13] security: phytec-pki: Add link to HAB docu Directly link to the HAB documentation. Signed-off-by: Leonard Anderweit --- source/security/common/phytec-pki.rsti | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/security/common/phytec-pki.rsti b/source/security/common/phytec-pki.rsti index 6c5bcc0ce..bc89d8e19 100644 --- a/source/security/common/phytec-pki.rsti +++ b/source/security/common/phytec-pki.rsti @@ -100,8 +100,9 @@ You can install the srktool with # or build from source host:~$ make -C code/obj.linux64 OSTYPE=linux64 ENCRYPTION=yes -More information about cst and HAB4 API you can find in the doc folder of -the imx-code-signing-tool repository. +More information about cst and the HABv4 API can be found in the `doc folder of +the imx-code-signing-tool repository +`_. Create TI K3 Keys ----------------- From c33472f86a18b83722c4f21d09557bba46af2614 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Tue, 28 Apr 2026 15:57:59 +0200 Subject: [PATCH 07/13] security: phytec-pki: Add ssh certificate chapter Add a chapter on ssh certificate creation. Signed-off-by: Leonard Anderweit --- source/security/common/phytec-pki.rsti | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/source/security/common/phytec-pki.rsti b/source/security/common/phytec-pki.rsti index bc89d8e19..b911d478d 100644 --- a/source/security/common/phytec-pki.rsti +++ b/source/security/common/phytec-pki.rsti @@ -490,3 +490,29 @@ Create RAUC Update Certificates You can create the key and certificate for RAUC with a PKI tool or openssl. More details on the `RAUC documentation `_ + +Create SSH Keys and Certificates +-------------------------------------- + +.. note:: + + Available from Yocto Walnascar + +First, create the user CA. + +.. code-block:: console + + host:~$ ssh-keygen -t ed25519 -f user_ca -C "User CA" + +This creates ``user_ca``, which should be kept save, and ``user_ca.pub``, which +will be installed on the target. + +Second, create the user private key and a corresponding public key, which is +signed by the user CA, both will be installed on the client accessing the +target. + +.. code-block:: console + + host:~$ ssh-keygen -t ed25519 -f user_root_ed25519 -a 32 -C "root" + # example with 24h access to the target + host:~$ ssh-keygen -s user_ca -I root -n root -V +24h user_root_ed25519.pub From eb83adb44c73dbd5a0d148467744b5b5d8e8403b Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Tue, 19 May 2026 11:25:33 +0200 Subject: [PATCH 08/13] security: devicetree-overlay: Update dynamic overlay handling Signed-off-by: Leonard Anderweit --- .../security/common/devicetree-overlay.rsti | 40 +++---------------- 1 file changed, 6 insertions(+), 34 deletions(-) diff --git a/source/security/common/devicetree-overlay.rsti b/source/security/common/devicetree-overlay.rsti index d30dc9b21..8a6f309eb 100644 --- a/source/security/common/devicetree-overlay.rsti +++ b/source/security/common/devicetree-overlay.rsti @@ -24,7 +24,7 @@ Device Tree Overlay for i.MX6UL and i.MX6 The barebox contains an Ethernet PHY detection, which boots the correct configuration from the FIT-image. -Device Tree Overlay for the other NXP SoCs +Device Tree Overlay for other SoCs -------------------------------------------- Build Time @@ -40,42 +40,14 @@ automatically added as a node to the signed FIT-image. Run Time ........ -The ``overlays`` variable can be either set directly in the U-Boot environment or -be a part of the external ``bootenv.txt`` environment. +Configuring device tree overlays through ``overlays.txt`` is disabled in secure +context as this file can't be signed and verified. -.. warning:: - - Manipulation Risk! The external ``bootenv.txt`` is not signed and protected - against manipulation, so overlays can be changed and deleted in the - ``bootenv.txt``. - -The ``overlays`` variable loaded from the external environment will always -overwrite the value from the environment saved directly in the flash. -By default, the ``overlays`` variable is not set directly in the U-Boot -environment but comes from the external ``bootenv.txt`` environment file. -It is also located in the boot partition of the SD card image. +Device tree overlays specified in the u-boot variable ``fit_overlay_conf`` will +be used. This variable can either be defined in the default u-boot environment +or in the ampliphy-boot bootscript. .. note:: Please use Device Tree Overlay only in the development stage of your product. Create a final Device Tree for your device for the production phase. - -Deactivate Device Tree Overlay Support -...................................... - -To disable the Device Tree Overlay support set the following variable in -``sources/meta-ampliphy/classes/secureboot.bbclass`` to true - -.. code-block:: bash - - FITIMAGE_NO_DTB_OVERLAYS ?= "true" - -All the machine-defined Device Tree Overlays will be added to the FIT-image. -If you do not want Device Tree Overlays in the FIT-image, -please remove fdto in the ``sources/meta-ampliphy/recipes-image/fitimage/phytec-secureboot-ramdisk-fitimage.bb`` -or in your custom FIT-image recipe. - -.. code-block:: bash - - FITIMAGE_SLOTS ?= "kernel fdt fdto ramdisk" - From 9f247221b3b18fda23bb6b7a44d0d88407652700 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Fri, 5 Jun 2026 15:17:30 +0200 Subject: [PATCH 09/13] security: secure-key-storage: Remove key generation script Move the key generation script to the older manuals. It will be re-added in a new chapter for new manuals. Signed-off-by: Leonard Anderweit --- .../security/common/secure-key-storage.rsti | 38 ------------------ source/security/scarthgap-sec.rst | 39 +++++++++++++++++++ 2 files changed, 39 insertions(+), 38 deletions(-) diff --git a/source/security/common/secure-key-storage.rsti b/source/security/common/secure-key-storage.rsti index bd5cf0ff5..898883db6 100644 --- a/source/security/common/secure-key-storage.rsti +++ b/source/security/common/secure-key-storage.rsti @@ -291,44 +291,6 @@ The following table list the supported key types for the different SoCs. | securecaam | caam | | x | | | +-------------+------------------+-------------+-------------+------------+-------------+ -Secure Key Storage Initialization with phySecureKeyStorage Tool -............................................................... - -The tool `physecurekeystorage-install `_ -is part of the ramdisk userspace of phytec-provisioning-initramfs and included -in the meta-ampliphy layer of the PHYTEC Standard BSP. - -The ``physecurekeystorage-install`` tool can initialize all supported secure key -storages of your machine, but always only one can be active. -For example, the phyBOARD-Polis-imx8mm supports Trusted TEE, Trusted TPM, -Trusted CAAM and Secure CAAM, but initialized is only Trusted TPM. - -.. code-block:: console - - target:~$ physecurekeystorage-install -h - - PHYTEC Install Script v1.7 for Secure Key Storage - - Usage: physecurekeystorage-install [PARAMETER] [ACTION] - - Example: - physecurekeystorage-install --newkeystorage trustedtpm - physecurekeystorage-install --deletekeystorage - physecurekeystorage-install --loadkeystorage - physecurekeystorage-install --pkcs11testkey - - One of the following action can be selected: - -n | --newkeystorage Create new Secure Key Storage - trustedcaam (only NXP controller) - trustedtee - trustedtpm - securecaam (black blob only NXP Vendor BSP) - -d | --deletekeystorage Erase the existing Secure Key Storage - -l | --loadkeystorage Load the existing Secure Key Storage - -p | --pkcs11testkey Create an ECC testkey with user pin 1234 - -h | --help This Help - -v | --version The version of physecurekeystorage-install - Cryptographic Token Interface PKCS#11 ------------------------------------- diff --git a/source/security/scarthgap-sec.rst b/source/security/scarthgap-sec.rst index caecefe48..1d701b938 100644 --- a/source/security/scarthgap-sec.rst +++ b/source/security/scarthgap-sec.rst @@ -91,6 +91,45 @@ read the correct sections fitting your platform. .. include:: common/devicetree-overlay.rsti .. _secure-key-storage-scarthgap: .. include:: common/secure-key-storage.rsti + +Secure Key Storage Initialization with phySecureKeyStorage Tool +--------------------------------------------------------------- + +The tool `physecurekeystorage-install `_ +is part of the ramdisk userspace of phytec-provisioning-initramfs and included +in the meta-ampliphy layer of the PHYTEC Standard BSP. + +The ``physecurekeystorage-install`` tool can initialize all supported secure key +storages of your machine, but always only one can be active. +For example, the phyBOARD-Polis-imx8mm supports Trusted TEE, Trusted TPM, +Trusted CAAM and Secure CAAM, but initialized is only Trusted TPM. + +.. code-block:: console + + target:~$ physecurekeystorage-install -h + + PHYTEC Install Script v1.7 for Secure Key Storage + + Usage: physecurekeystorage-install [PARAMETER] [ACTION] + + Example: + physecurekeystorage-install --newkeystorage trustedtpm + physecurekeystorage-install --deletekeystorage + physecurekeystorage-install --loadkeystorage + physecurekeystorage-install --pkcs11testkey + + One of the following action can be selected: + -n | --newkeystorage Create new Secure Key Storage + trustedcaam (only NXP controller) + trustedtee + trustedtpm + securecaam (black blob only NXP Vendor BSP) + -d | --deletekeystorage Erase the existing Secure Key Storage + -l | --loadkeystorage Load the existing Secure Key Storage + -p | --pkcs11testkey Create an ECC testkey with user pin 1234 + -h | --help This Help + -v | --version The version of physecurekeystorage-install + .. include:: common/secure-storage.rsti .. include:: common/hardening.rsti .. _physical-security-scarthgap: From 40a17808c3709ea192c941eaf801402137321238 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Wed, 10 Jun 2026 13:31:33 +0200 Subject: [PATCH 10/13] security: secure-storage: Move outdated content to older manuals Signed-off-by: Leonard Anderweit --- source/security/common/secure-storage.rsti | 180 --------------------- source/security/kirkstone-sec.rst | 180 +++++++++++++++++++++ source/security/scarthgap-sec.rst | 180 +++++++++++++++++++++ 3 files changed, 360 insertions(+), 180 deletions(-) diff --git a/source/security/common/secure-storage.rsti b/source/security/common/secure-storage.rsti index 6537bb0c2..97a23feb8 100644 --- a/source/security/common/secure-storage.rsti +++ b/source/security/common/secure-storage.rsti @@ -53,183 +53,3 @@ Requirements for Filesystem Encryption * Secure Boot must be activated and the device must be locked for proper secure key storage. * A user login should be activated for access control on runtime. - -Boot Process Flow ------------------ - -* bootloader verifies FIT-image with linux-kernel image, device tree, and - ramdisk before they are executed -* Linux kernel executes the ramdisk (read-only filesystem) -* The bootscript loads the authenticated encrypted filesystem encryption key - with the CAAM, TEE or TPM unit in the RAM and encrypts the filesystem. After - the encryption, the root filesystem will be switched and the boot process - continues. - -Starting the Build Process --------------------------- - -Filesystem integrity and encryption are included in the ``DISTRO_FEATURES`` -``secureboot`` and ``securestorage``. - -You can choose in the ``sources/meta-ampliphy/conf/distro/common-secure.inc`` -between - - * ``fileauthorenc``: use integrity or encrypted filesystem - * ``fileauthandenc``: use integrity and encrypted filesystem - -This configuration is important for the RAUC update system because the use of -integrity and encrypted filesystem are stacked and the number of device-mappers -is doubled to use integrity or encrypted filesystem. - -.. code-block:: bash - - DISTRO_FEATURES += "securestorage" - #possible types: fileauthorenc , fileauthandenc - SECURE_STORAGE_TYPE = "fileauthandenc" - OVERRIDES_append = ":securestorage:${SECURE_STORAGE_TYPE}" - -This configuration changes the RAUC ``system.conf`` configuration in the rootfs -image for the target, too. The device changes from the ``/dev/mtdblockX`` to the -device mapper ``/dev/dm-x``. With this changes the integrity and the encryption are -retained during an update. - -Setup Secure Storage on your Device ------------------------------------ - -The filesystem encryption ensures the target has a unique key or an equal key -per device. - -The filesystem encryption process flow: - -* The filesystem encryption key is generated and stored encrypted with CAAM, - TEE, or TPM. -* Encryption is initialized. -* The partition is formatted. -* Data is copied to the encrypted partition. - -First Boot -.......... - -From a high-level point of view, an eMMC device is like an SD card. Therefore, -it is possible to flash the image phytec-provisioning-image -from the Yocto build system directly to the SD card. The image contains the -signed bootloader and signed FIT-image with an initramfs. - -If your filesystem is not initialized, is damaged, or the key blob is deleted, -then you can reinstall the encrypted filesystem with the following instructions. - -* Boot the phytec-provisioning-image from the SD card or load the provisioning - fitImage with tftp to the memory in the bootloader -* The device stops with the following message because there is no encrypted key - stored in the folder ``/mnt/config/secrets``: - -The default user is root with the password root: - -.. note:: - - If there is no login in 60s, then the system goes to power off - - .. code-block:: console - - Login timed out after 60 second - [ERROR] Key and Filesystem Initialization - The system will poweroff in 10 seconds - reboot: Power down - -* If this is your first boot from the device and no image is on the eMMC, - please flash an image to the eMMC. - -Key Generation for Secure Storage -................................. - -Please follow the instructions in the chapter |secure-key-storage-link| - -Secure Storage Initialization with phySecureStorage Tool -........................................................ - -The tool ``physecurestorage-install`` is part of the initramfs userspace of the -phytec-provisioning-image. - -The ``physecurestorage-install`` tool can initialize the filesystem with encryption, -integrity, or both methods together. - -.. code-block:: console - - target:~$ physecurestorage-install -h - - PHYTEC Install Script v1.5 for Secure Storage - - Usage: physecurestorage-install [PARAMETER] [ACTION] - - Example: - physecurestorage-install --flashpath /dev/mmcblk0 - --filesystem /media/phytec-security-image.ext4 - --flashlayout 5,6 - --newsecurestorage intenc - - One of the following action can be selected: - -n | --newsecurestorage Create new Secure Storage of type - int Root File System with integrity - enc Encrypted root file system - intenc Encrypted root file system with integrity - -h | --help This Help - -v | --version The version of the physecurestorage-install - - The following PARAMETER must be set for new Secure Storage: - -p | --flashpath - -s | --filesystem - -l | --flashlayout partition number for the rootfs partitions - 5,6 rootfs partitions are 5 and 6 - -L | --labelname label name for the partition - -* The parameter is the eMMC device. -* The parameter is the path to tar.gz archive of the filesystem, - which should be installed on the flash device. -* Please copy the filesystem image, -.tar.gz, to a USB or - MMC drive so that it can be installed on the target. If partup packages are - used for initial flashing, then mount the partup package as type squashfs - first and find the root filesystem there. -* The parameter contains the rootfs partition. -* The parameter RAUC initializes both RAUC rootfs partitions. -* After the installation, power off the system: - -.. code-block:: console - - target:~$ poweroff -f - -* Restart the system. After a successful installation, the system will boot to - the kernel login console. - -Recover an Initialized Device -............................. - -If your filesystem is damaged or the key blob is deleted, then you can -reinstall the encrypted filesystem with the following options. - - 1. Reinitialize your device with the phytec-provisioning-image from the SD - card (Boot in ramdisk) - 2. Boot in rescue mode of the existing flash image with minimal tools support - -The following commands are for starting the rescue mode with a booted device -from eMMC: - - * Stop booting in the bootloader. The Protection Shield Level low is in - default with password: root - * Add Linux bootargs in the bootloader and boot the fitImage from the eMMC: - - * for barebox (i.MX6 and i.MX6UL) - - .. code-block:: - - barebox$ global linux.bootargs.rescue="rescue=1" - barebox$ boot - - * for u-boot: - - .. code-block:: - - u-boot=> run loadraucimage - u-boot=> run raucargs - u-boot=> setenv bootargs ${bootargs} rescue=1 - u-boot=> bootm ${loadaddr} - diff --git a/source/security/kirkstone-sec.rst b/source/security/kirkstone-sec.rst index 1d1bfd389..bb6d6b28a 100644 --- a/source/security/kirkstone-sec.rst +++ b/source/security/kirkstone-sec.rst @@ -703,6 +703,186 @@ full-featured software library for general-purpose cryptography and secure communication. .. include:: common/secure-storage.rsti + +Boot Process Flow +----------------- + +* bootloader verifies FIT-image with linux-kernel image, device tree, and + ramdisk before they are executed +* Linux kernel executes the ramdisk (read-only filesystem) +* The bootscript loads the authenticated encrypted filesystem encryption key + with the CAAM, TEE or TPM unit in the RAM and encrypts the filesystem. After + the encryption, the root filesystem will be switched and the boot process + continues. + +Starting the Build Process +-------------------------- + +Filesystem integrity and encryption are included in the ``DISTRO_FEATURES`` +``secureboot`` and ``securestorage``. + +You can choose in the ``sources/meta-ampliphy/conf/distro/common-secure.inc`` +between + + * ``fileauthorenc``: use integrity or encrypted filesystem + * ``fileauthandenc``: use integrity and encrypted filesystem + +This configuration is important for the RAUC update system because the use of +integrity and encrypted filesystem are stacked and the number of device-mappers +is doubled to use integrity or encrypted filesystem. + +.. code-block:: bash + + DISTRO_FEATURES += "securestorage" + #possible types: fileauthorenc , fileauthandenc + SECURE_STORAGE_TYPE = "fileauthandenc" + OVERRIDES_append = ":securestorage:${SECURE_STORAGE_TYPE}" + +This configuration changes the RAUC ``system.conf`` configuration in the rootfs +image for the target, too. The device changes from the ``/dev/mtdblockX`` to the +device mapper ``/dev/dm-x``. With this changes the integrity and the encryption are +retained during an update. + +Setup Secure Storage on your Device +----------------------------------- + +The filesystem encryption ensures the target has a unique key or an equal key +per device. + +The filesystem encryption process flow: + +* The filesystem encryption key is generated and stored encrypted with CAAM, + TEE, or TPM. +* Encryption is initialized. +* The partition is formatted. +* Data is copied to the encrypted partition. + +First Boot +.......... + +From a high-level point of view, an eMMC device is like an SD card. Therefore, +it is possible to flash the image phytec-provisioning-image +from the Yocto build system directly to the SD card. The image contains the +signed bootloader and signed FIT-image with an initramfs. + +If your filesystem is not initialized, is damaged, or the key blob is deleted, +then you can reinstall the encrypted filesystem with the following instructions. + +* Boot the phytec-provisioning-image from the SD card or load the provisioning + fitImage with tftp to the memory in the bootloader +* The device stops with the following message because there is no encrypted key + stored in the folder ``/mnt/config/secrets``: + +The default user is root with the password root: + +.. note:: + + If there is no login in 60s, then the system goes to power off + + .. code-block:: console + + Login timed out after 60 second + [ERROR] Key and Filesystem Initialization + The system will poweroff in 10 seconds + reboot: Power down + +* If this is your first boot from the device and no image is on the eMMC, + please flash an image to the eMMC. + +Key Generation for Secure Storage +................................. + +Please follow the instructions in the chapter |secure-key-storage-link| + +Secure Storage Initialization with phySecureStorage Tool +........................................................ + +The tool ``physecurestorage-install`` is part of the initramfs userspace of the +phytec-provisioning-image. + +The ``physecurestorage-install`` tool can initialize the filesystem with encryption, +integrity, or both methods together. + +.. code-block:: console + + target:~$ physecurestorage-install -h + + PHYTEC Install Script v1.5 for Secure Storage + + Usage: physecurestorage-install [PARAMETER] [ACTION] + + Example: + physecurestorage-install --flashpath /dev/mmcblk0 + --filesystem /media/phytec-security-image.ext4 + --flashlayout 5,6 + --newsecurestorage intenc + + One of the following action can be selected: + -n | --newsecurestorage Create new Secure Storage of type + int Root File System with integrity + enc Encrypted root file system + intenc Encrypted root file system with integrity + -h | --help This Help + -v | --version The version of the physecurestorage-install + + The following PARAMETER must be set for new Secure Storage: + -p | --flashpath + -s | --filesystem + -l | --flashlayout partition number for the rootfs partitions + 5,6 rootfs partitions are 5 and 6 + -L | --labelname label name for the partition + +* The parameter is the eMMC device. +* The parameter is the path to tar.gz archive of the filesystem, + which should be installed on the flash device. +* Please copy the filesystem image, -.tar.gz, to a USB or + MMC drive so that it can be installed on the target. If partup packages are + used for initial flashing, then mount the partup package as type squashfs + first and find the root filesystem there. +* The parameter contains the rootfs partition. +* The parameter RAUC initializes both RAUC rootfs partitions. +* After the installation, power off the system: + +.. code-block:: console + + target:~$ poweroff -f + +* Restart the system. After a successful installation, the system will boot to + the kernel login console. + +Recover an Initialized Device +............................. + +If your filesystem is damaged or the key blob is deleted, then you can +reinstall the encrypted filesystem with the following options. + + 1. Reinitialize your device with the phytec-provisioning-image from the SD + card (Boot in ramdisk) + 2. Boot in rescue mode of the existing flash image with minimal tools support + +The following commands are for starting the rescue mode with a booted device +from eMMC: + + * Stop booting in the bootloader. The Protection Shield Level low is in + default with password: root + * Add Linux bootargs in the bootloader and boot the fitImage from the eMMC: + + * for barebox (i.MX6 and i.MX6UL) + + .. code-block:: + + barebox$ global linux.bootargs.rescue="rescue=1" + barebox$ boot + + * for u-boot: + + .. code-block:: + + u-boot=> run loadraucimage + u-boot=> run raucargs + u-boot=> setenv bootargs ${bootargs} rescue=1 + u-boot=> bootm ${loadaddr} + .. include:: common/hardening.rsti Physical security diff --git a/source/security/scarthgap-sec.rst b/source/security/scarthgap-sec.rst index 1d701b938..afa0ac199 100644 --- a/source/security/scarthgap-sec.rst +++ b/source/security/scarthgap-sec.rst @@ -131,6 +131,186 @@ Trusted CAAM and Secure CAAM, but initialized is only Trusted TPM. -v | --version The version of physecurekeystorage-install .. include:: common/secure-storage.rsti + +Boot Process Flow +----------------- + +* bootloader verifies FIT-image with linux-kernel image, device tree, and + ramdisk before they are executed +* Linux kernel executes the ramdisk (read-only filesystem) +* The bootscript loads the authenticated encrypted filesystem encryption key + with the CAAM, TEE or TPM unit in the RAM and encrypts the filesystem. After + the encryption, the root filesystem will be switched and the boot process + continues. + +Starting the Build Process +-------------------------- + +Filesystem integrity and encryption are included in the ``DISTRO_FEATURES`` +``secureboot`` and ``securestorage``. + +You can choose in the ``sources/meta-ampliphy/conf/distro/common-secure.inc`` +between + + * ``fileauthorenc``: use integrity or encrypted filesystem + * ``fileauthandenc``: use integrity and encrypted filesystem + +This configuration is important for the RAUC update system because the use of +integrity and encrypted filesystem are stacked and the number of device-mappers +is doubled to use integrity or encrypted filesystem. + +.. code-block:: bash + + DISTRO_FEATURES += "securestorage" + #possible types: fileauthorenc , fileauthandenc + SECURE_STORAGE_TYPE = "fileauthandenc" + OVERRIDES_append = ":securestorage:${SECURE_STORAGE_TYPE}" + +This configuration changes the RAUC ``system.conf`` configuration in the rootfs +image for the target, too. The device changes from the ``/dev/mtdblockX`` to the +device mapper ``/dev/dm-x``. With this changes the integrity and the encryption are +retained during an update. + +Setup Secure Storage on your Device +----------------------------------- + +The filesystem encryption ensures the target has a unique key or an equal key +per device. + +The filesystem encryption process flow: + +* The filesystem encryption key is generated and stored encrypted with CAAM, + TEE, or TPM. +* Encryption is initialized. +* The partition is formatted. +* Data is copied to the encrypted partition. + +First Boot +.......... + +From a high-level point of view, an eMMC device is like an SD card. Therefore, +it is possible to flash the image phytec-provisioning-image +from the Yocto build system directly to the SD card. The image contains the +signed bootloader and signed FIT-image with an initramfs. + +If your filesystem is not initialized, is damaged, or the key blob is deleted, +then you can reinstall the encrypted filesystem with the following instructions. + +* Boot the phytec-provisioning-image from the SD card or load the provisioning + fitImage with tftp to the memory in the bootloader +* The device stops with the following message because there is no encrypted key + stored in the folder ``/mnt/config/secrets``: + +The default user is root with the password root: + +.. note:: + + If there is no login in 60s, then the system goes to power off + + .. code-block:: console + + Login timed out after 60 second + [ERROR] Key and Filesystem Initialization + The system will poweroff in 10 seconds + reboot: Power down + +* If this is your first boot from the device and no image is on the eMMC, + please flash an image to the eMMC. + +Key Generation for Secure Storage +................................. + +Please follow the instructions in the chapter |secure-key-storage-link| + +Secure Storage Initialization with phySecureStorage Tool +........................................................ + +The tool ``physecurestorage-install`` is part of the initramfs userspace of the +phytec-provisioning-image. + +The ``physecurestorage-install`` tool can initialize the filesystem with encryption, +integrity, or both methods together. + +.. code-block:: console + + target:~$ physecurestorage-install -h + + PHYTEC Install Script v1.5 for Secure Storage + + Usage: physecurestorage-install [PARAMETER] [ACTION] + + Example: + physecurestorage-install --flashpath /dev/mmcblk0 + --filesystem /media/phytec-security-image.ext4 + --flashlayout 5,6 + --newsecurestorage intenc + + One of the following action can be selected: + -n | --newsecurestorage Create new Secure Storage of type + int Root File System with integrity + enc Encrypted root file system + intenc Encrypted root file system with integrity + -h | --help This Help + -v | --version The version of the physecurestorage-install + + The following PARAMETER must be set for new Secure Storage: + -p | --flashpath + -s | --filesystem + -l | --flashlayout partition number for the rootfs partitions + 5,6 rootfs partitions are 5 and 6 + -L | --labelname label name for the partition + +* The parameter is the eMMC device. +* The parameter is the path to tar.gz archive of the filesystem, + which should be installed on the flash device. +* Please copy the filesystem image, -.tar.gz, to a USB or + MMC drive so that it can be installed on the target. If partup packages are + used for initial flashing, then mount the partup package as type squashfs + first and find the root filesystem there. +* The parameter contains the rootfs partition. +* The parameter RAUC initializes both RAUC rootfs partitions. +* After the installation, power off the system: + +.. code-block:: console + + target:~$ poweroff -f + +* Restart the system. After a successful installation, the system will boot to + the kernel login console. + +Recover an Initialized Device +............................. + +If your filesystem is damaged or the key blob is deleted, then you can +reinstall the encrypted filesystem with the following options. + + 1. Reinitialize your device with the phytec-provisioning-image from the SD + card (Boot in ramdisk) + 2. Boot in rescue mode of the existing flash image with minimal tools support + +The following commands are for starting the rescue mode with a booted device +from eMMC: + + * Stop booting in the bootloader. The Protection Shield Level low is in + default with password: root + * Add Linux bootargs in the bootloader and boot the fitImage from the eMMC: + + * for barebox (i.MX6 and i.MX6UL) + + .. code-block:: + + barebox$ global linux.bootargs.rescue="rescue=1" + barebox$ boot + + * for u-boot: + + .. code-block:: + + u-boot=> run loadraucimage + u-boot=> run raucargs + u-boot=> setenv bootargs ${bootargs} rescue=1 + u-boot=> bootm ${loadaddr} + .. include:: common/hardening.rsti .. _physical-security-scarthgap: .. include:: common/physical-security.rsti From b1cf818fd8409b4f92ef4c3d55f9233d0c21e93f Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Tue, 9 Jun 2026 16:24:30 +0200 Subject: [PATCH 11/13] security: secure-boot: Move outdated content to older manuals Signed-off-by: Leonard Anderweit --- source/security/common/secure-boot.rsti | 152 ------------------------ source/security/kirkstone-sec.rst | 50 ++++++++ source/security/scarthgap-sec.rst | 50 ++++++++ 3 files changed, 100 insertions(+), 152 deletions(-) diff --git a/source/security/common/secure-boot.rsti b/source/security/common/secure-boot.rsti index 4b9f51de9..5992fd2d4 100644 --- a/source/security/common/secure-boot.rsti +++ b/source/security/common/secure-boot.rsti @@ -73,155 +73,3 @@ device-tree and optional initramfs. The FIT-image are signed in the Yocto build with a Private Key. The public key is on the target, compiled in the bootloader or the NXP HAB keys are used. Documentation about FIT is available in the `Flattened Image Tree project `_. - -There are two different Yocto classes for creation of a signed FIT-image. - -* PHYTEC ``sources/meta-phytec/classes/fitimage.bbclass`` - - * With FIT-image recipes you can define custom, more refined FIT-images. - * Example for FIT-image recipes are in ``sources/meta-ampliphy/recipes-images/fitimage/`` - * To create custom FIT-image, you need to specify some variables in the - recipe: - - * FITIMAGE_SLOTS: Use this to list all slot classes for which the - FIT-image should contain images. A value of "kernel fdt fdtapply", - for example, will create a manifest with images for two slot classes - - kernel and devicetree. - * FITIMAGE_SLOT_: For each slot class, set this to the image - (recipe) name which builds the artifact you intend to place in the slot - class. - * FITIMAGE_SLOT_[type]: For each slot class, set this to the - type of image you intend to place in this slot. Possible types are the - kernel, fdt, fdto, fdtapply, or ramdisk. - * FITIMAGE_SLOT_[file]: For slot type kernel, fdt, fdt0 and - fdtapply set this to the file of the image you intend to place in this - slot. - * FITIMAGE_SLOT_[fstype]: For slot type ramdisk, set this to - the filesystem type of image you intend to place in this slot. - * FITIMAGE_SLOT_[name]: For slot type fdtapply, set this to - the final device tree and configuration name. - -* Poky ``sources/poky/meta/classes-recipe/kernel-fitimage.bbclass`` - - * This is the standard upstream FIT-image class in Yocto mainly for u-boot, - which builts one FIT-image with initramfs and without initramfs. - -Initially, the PHYTEC FIT-image class was used to create the FIT-images, because -it supports barebox and u-boot and you can define more refined FIT-images. -Since security has increasingly become an integral part of the SoC -manufacturer's BSPs, which use the kernel-fitimage, PHYTEC has decided to -gradually switch to this class, too. - -Configuration Class for Signing Images --------------------------------------- -All variables to adjust the bootloader and kernel fitImage signing process can -be found in the ``source/meta-ampliphy/secureboot.bbclass`` - -First of all, the necessary variables for signing the bootloader for the -different SoC types need to be defined. The variable ``BOOTLOADER_SIGN`` is -obsolete, because the ``DISTRO_FEATURES="secureboot"`` includes the bootloader -signing. - -.. code-block:: bash - - BOOTLOADER_SIGN ??= "true" - BOOTLOADER_SIGN[type] = "boolean" - - CERT_PATH ??= "${OEROOT}/../../phytec-dev-ca" - # for NXP HABv4 based systems - BOOTLOADER_SIGN_IMG_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem" - BOOTLOADER_SIGN_CSF_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem" - BOOTLOADER_SIGN_SRKFUSE_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/SRK_1_2_3_4_table.bin" - BOOTLOADER_HABV4_SRK_INDEX ??= "0" - - # AHAB - AHAB_SRK_TABLE_BIN ?= "${CERT_PATH}/nxp_ahab_pki/crts/SRK_1_2_3_4_table.bin" - AHAB_SRK_PUB_CERT ?= "${CERT_PATH}/nxp_ahab_pki/crts/SRK1_sha512_secp521r1_v3_usr_crt.pem" - AHAB_SRK_INDEX ?= "0" - - # for TI K3 - BOOTLOADER_TI_K3_MPK_KEY ??= "${CERT_PATH}/ti_k3/keys/phytecSMPK.pem" - BOOTLOADER_TI_K3_DEGENERATE_KEY ??= "${CERT_PATH}/ti_k3/keys/ti-degenerate-key.pem" - -In the following view you can see the necessary variables for signing with the -PHYTEC FIT-image class. The ``FITIMAGE_PUBKEY_SIGNATURE_PATH`` is only important, -when using the ``FITIMAGE_SIGN_ENGINE="software"``. This means, that the u-boot -validates the kernel fitImage und uses the compiled-in public key. -The alternative is that the NXP HAB unit validates the kernel fitImage, then -the ``FITIMAGE_SIGN_ENGINE="nxphab"`` must be set. This is only possible for -NXP SoCs with HAB unit and u-boot as bootloader. -The following configuration is part of in the ``sources/meta-ampliphy/secureboot.bbclass`` - -.. code-block:: bash - - FITIMAGE_SIGN ?= "true" - FITIMAGE_SIGN[type] = "boolean" - - FITIMAGE_NO_DTB_OVERLAYS ?= "false" - FITIMAGE_NO_DTB_OVERLAYS[type] = "boolean" - - FITIMAGE_SIGNER ?= "customer" - FITIMAGE_PUBKEY_SIGNATURE_PATH ?= "${WORKDIR}/signature_node.dtsi" - - FITIMAGE_SIGN_ENGINE ?= "software" - - FITIMAGE_SIGN_KEY_PATH ?= "${CERT_PATH}/fit/FIT-4096.key" - FITIMAGE_HASH ?= "sha256" - FITIMAGE_SIGNATURE_ENCRYPTION ?= "rsa4096" - FITIMAGE_SIGNER_VERSION ?= "vPD20.0.0" - -The signing with the poky kernel-fitimage class needs the following -configuration in - -* machine configuration in ``sources/meta-phytec/conf/machine`` for the kernel, - initrd, device-tree and device-tree overlay ``LOADADDRESS`` and - ``ENTRYPOINT`` addresses -* ``source/meta-ampliphy/secureboot.bbclass`` for the signing key parameter - - .. code-block:: bash - - UBOOT_SIGN_KEYDIR = "${CERT_PATH}/fit" - UBOOT_SIGN_KEYNAME = "FIT-4096" - FIT_SIGN_ALG = "rsa4096" - FIT_HASH_ALG = "sha256" - -* ``sources/meta-ampliyphy/conf/distro`` file for the ``INITRAMFS_IMAGE``. - - * |distro-secure| and |distro-secure-vendor|: - ``INITRAMFS_IMAGE = "phytec-secureboot-initramfs"`` - * |distro-provisioning| and |distro-provisioning-vendor|: - ``INITRAMFS_IMAGE = "phytec-provisioning-initramfs"`` - -Building a Signed Image ------------------------ - -To build a signed provisioning image for the configuration of the device -which can boot from SD card or Serial Downloader, the ``DISTRO`` needs to -be set to |distro-provisioning-vendor| or |distro-provisioning|. -The main parts for the provisioning-image are the bootloader and the FIT-image, -which includes an initramfs with all necessary tools. - -.. code-block:: console - - # for NXP SoC - host:~$ bitbake phytec-provisioning-image - - # for TI K3 SoC - host:~$ bitbake phytec-headless-image - -To build the |image-secure-name| for the eMMC or ubifs with RAUC update support, -then the ``DISTRO`` needs to be set to |distro-secure-vendor| or -|distro-secure|. - -.. code-block:: console - :substitutions: - - # for all SoC - host:~$ bitbake |image-secure-name| - -.. note:: - If you have some boot warnings or errors like "/initrd.image: incomplete - write" or the kernel boot fails, then please check the size for Contiguous - Memory Allocation (CMA; kernel boot parameter, setting in bootloader). The - allocated RAM for CMA can be too much, which is important for systems with - 256 MiB or 512 MiB RAM. diff --git a/source/security/kirkstone-sec.rst b/source/security/kirkstone-sec.rst index bb6d6b28a..a8df54784 100644 --- a/source/security/kirkstone-sec.rst +++ b/source/security/kirkstone-sec.rst @@ -70,6 +70,56 @@ read the correct sections fitting your platform. .. _secure-boot-kirkstone: .. include:: common/secure-boot.rsti +There are two different Yocto classes for creation of a signed FIT-image. + +* PHYTEC ``sources/meta-phytec/classes/fitimage.bbclass`` + + * With FIT-image recipes you can define custom, more refined FIT-images. + * Example for FIT-image recipes are in ``sources/meta-ampliphy/recipes-images/fitimage/`` + * To create custom FIT-image, you need to specify some variables in the + recipe: + + * FITIMAGE_SLOTS: Use this to list all slot classes for which the + FIT-image should contain images. A value of "kernel fdt fdtapply", + for example, will create a manifest with images for two slot classes - + kernel and devicetree. + * FITIMAGE_SLOT_: For each slot class, set this to the image + (recipe) name which builds the artifact you intend to place in the slot + class. + * FITIMAGE_SLOT_[type]: For each slot class, set this to the + type of image you intend to place in this slot. Possible types are the + kernel, fdt, fdto, fdtapply, or ramdisk. + * FITIMAGE_SLOT_[file]: For slot type kernel, fdt, fdt0 and + fdtapply set this to the file of the image you intend to place in this + slot. + * FITIMAGE_SLOT_[fstype]: For slot type ramdisk, set this to + the filesystem type of image you intend to place in this slot. + * FITIMAGE_SLOT_[name]: For slot type fdtapply, set this to + the final device tree and configuration name. + +* Poky ``sources/poky/meta/classes-recipe/kernel-fitimage.bbclass`` + + * This is the standard upstream FIT-image class in Yocto mainly for u-boot, + which builts one FIT-image with initramfs and without initramfs. + +Initially, the PHYTEC FIT-image class was used to create the FIT-images, because +it supports barebox and u-boot and you can define more refined FIT-images. +Since security has increasingly become an integral part of the SoC +manufacturer's BSPs, which use the kernel-fitimage, PHYTEC has decided to +gradually switch to this class, too. + +Configuration Class for Signing Images +-------------------------------------- +All variables to adjust the bootloader and kernel fitImage signing process can +be found in the ``source/meta-ampliphy/secureboot.bbclass`` + +First of all, the necessary variables for signing the bootloader for the +different SoC types need to be defined. The variable ``BOOTLOADER_SIGN`` is +obsolete, because the ``DISTRO_FEATURES="secureboot"`` includes the bootloader +signing. + +.. code-block:: bash + Activate Secure Boot on the Device ================================== diff --git a/source/security/scarthgap-sec.rst b/source/security/scarthgap-sec.rst index afa0ac199..bba9004ad 100644 --- a/source/security/scarthgap-sec.rst +++ b/source/security/scarthgap-sec.rst @@ -86,6 +86,56 @@ read the correct sections fitting your platform. .. include:: common/distro-using.rsti .. _secure-boot-scarthgap: .. include:: common/secure-boot.rsti + +There are two different Yocto classes for creation of a signed FIT-image. + +* PHYTEC ``sources/meta-phytec/classes/fitimage.bbclass`` + + * With FIT-image recipes you can define custom, more refined FIT-images. + * Example for FIT-image recipes are in ``sources/meta-ampliphy/recipes-images/fitimage/`` + * To create custom FIT-image, you need to specify some variables in the + recipe: + + * FITIMAGE_SLOTS: Use this to list all slot classes for which the + FIT-image should contain images. A value of "kernel fdt fdtapply", + for example, will create a manifest with images for two slot classes - + kernel and devicetree. + * FITIMAGE_SLOT_: For each slot class, set this to the image + (recipe) name which builds the artifact you intend to place in the slot + class. + * FITIMAGE_SLOT_[type]: For each slot class, set this to the + type of image you intend to place in this slot. Possible types are the + kernel, fdt, fdto, fdtapply, or ramdisk. + * FITIMAGE_SLOT_[file]: For slot type kernel, fdt, fdt0 and + fdtapply set this to the file of the image you intend to place in this + slot. + * FITIMAGE_SLOT_[fstype]: For slot type ramdisk, set this to + the filesystem type of image you intend to place in this slot. + * FITIMAGE_SLOT_[name]: For slot type fdtapply, set this to + the final device tree and configuration name. + +* Poky ``sources/poky/meta/classes-recipe/kernel-fitimage.bbclass`` + + * This is the standard upstream FIT-image class in Yocto mainly for u-boot, + which builts one FIT-image with initramfs and without initramfs. + +Initially, the PHYTEC FIT-image class was used to create the FIT-images, because +it supports barebox and u-boot and you can define more refined FIT-images. +Since security has increasingly become an integral part of the SoC +manufacturer's BSPs, which use the kernel-fitimage, PHYTEC has decided to +gradually switch to this class, too. + +Configuration Class for Signing Images +-------------------------------------- +All variables to adjust the bootloader and kernel fitImage signing process can +be found in the ``source/meta-ampliphy/secureboot.bbclass`` + +First of all, the necessary variables for signing the bootloader for the +different SoC types need to be defined. The variable ``BOOTLOADER_SIGN`` is +obsolete, because the ``DISTRO_FEATURES="secureboot"`` includes the bootloader +signing. + +.. code-block:: bash .. include:: common/activate-secureboot.rsti .. include:: common/kernel-module-signing.rsti .. include:: common/devicetree-overlay.rsti From fe43f774769d04103dd7e6f9cef674dd6b01a70c Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Thu, 11 Jun 2026 11:14:38 +0200 Subject: [PATCH 12/13] security: secure-boot: Add boot script Signed-off-by: Leonard Anderweit --- source/security/common/secure-boot.rsti | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/security/common/secure-boot.rsti b/source/security/common/secure-boot.rsti index 5992fd2d4..3c6e7a26c 100644 --- a/source/security/common/secure-boot.rsti +++ b/source/security/common/secure-boot.rsti @@ -39,9 +39,10 @@ SoCs of the same vendor. The main boot process is the following 2. u-boot SPL loads u-boot proper from the FIT-image and ATF (ARM Trusted Firmware) and optionally OP-TEE. -3. Then, u-boot loads and verifies the FIT-image containing a Linux kernel, - DTB, and ramdisk. (**Boot Step 2**) -4. If built with signed kernel modules (standard), Linux will only load kernel +3. Then, u-boot loads and verifies the boot script. (**Boot Step 2**) +4. Next, u-boot executes the boot script, which loads and verifies the FIT-image + containing a Linux kernel, DTB, and ramdisk. (**Boot Step 3**) +5. If built with signed kernel modules (standard), Linux will only load kernel modules verified with a kernel compiled-in public key If you use the DISTRO_FEATURE secureboot or a TI HS-SE machine variant, then From d3dd78409973431a201065c5304806c0e8631b27 Mon Sep 17 00:00:00 2001 From: Leonard Anderweit Date: Tue, 19 May 2026 11:56:01 +0200 Subject: [PATCH 13/13] security: Add walnascar manual Replace the head security manual with a walnascar security manual. The manual is now structured as a how to. Signed-off-by: Leonard Anderweit --- source/conf.py | 6 +- source/security/common/booting-securiphy.rsti | 54 +++++++++ source/security/common/build-securiphy.rsti | 57 +++++++++ source/security/common/introduction.rsti | 74 ++++++++++++ source/security/common/key-management.rsti | 70 +++++++++++ .../security/common/provisioning-scripts.rsti | 110 ++++++++++++++++++ source/security/common/provisioning.rsti | 82 +++++++++++++ source/security/common/recover-securiphy.rsti | 8 ++ source/security/common/update-securiphy.rsti | 31 +++++ source/security/head-sec.rst | 67 ----------- source/security/manual-index.rst | 6 +- source/security/walnascar-sec.rst | 70 +++++++++++ 12 files changed, 562 insertions(+), 73 deletions(-) create mode 100644 source/security/common/booting-securiphy.rsti create mode 100644 source/security/common/build-securiphy.rsti create mode 100644 source/security/common/introduction.rsti create mode 100644 source/security/common/key-management.rsti create mode 100644 source/security/common/provisioning-scripts.rsti create mode 100644 source/security/common/provisioning.rsti create mode 100644 source/security/common/recover-securiphy.rsti create mode 100644 source/security/common/update-securiphy.rsti delete mode 100644 source/security/head-sec.rst create mode 100644 source/security/walnascar-sec.rst diff --git a/source/conf.py b/source/conf.py index c65e662fd..9bb76d761 100644 --- a/source/conf.py +++ b/source/conf.py @@ -475,9 +475,9 @@ False, ), ( - 'security/head-sec', - 'head-sec.tex', - 'Security Manual DRAFT', + 'security/walnascar-sec', + 'walnascar-sec.tex', + 'Security Manual Walnascar', 'PHYTEC Messtechnik GmbH', 'manual', False, diff --git a/source/security/common/booting-securiphy.rsti b/source/security/common/booting-securiphy.rsti new file mode 100644 index 000000000..bbbca2c87 --- /dev/null +++ b/source/security/common/booting-securiphy.rsti @@ -0,0 +1,54 @@ +Booting securiPHY +================= + +After successfully provisioning the device you can use the freshly installed +securiPHY system. + +Set the boot jumper to eMMC and power the device. + +SSH Certificate Authentication Login +------------------------------------ + +Once the ``phytec-securiphy-image`` is running, the serial console only shows +the kernel log. Login is only possible with ssh now. + +Login with development certificates +................................... +The keys and certificates for ssh access are included in `phytec-dev-ca +`__. Download and extract the latest +release. + +.. code-block:: console + + host:~$ cd phytec-dev-ca/ssh-ca/user-root + host:~$ ssh-add user_root_ed25519 # enter password sshtest + +Check if private key and certificate have been added successfully. + +.. code-block:: console + + host:~$ ssh-add -l + 256 SHA256:/Cw8W1Z0N/XFCmLvBLDPDuwh+aFYWKWWinLxX/Rx918 root (ED25519) + 256 SHA256:/Cw8W1Z0N/XFCmLvBLDPDuwh+aFYWKWWinLxX/Rx918 root (ED25519-CERT) + +After that, connect to the board. + +.. code-block:: console + + host:~$ ssh -v -o IdentitiesOnly=yes -i user_root_ed25519 root@192.168.3.11 + +Create user certificate +....................... + +The development user certificate `user_root_ed25519-cert.pub` allows +unrestricted access to the target device. A certificate with restricted access +can be created as follows: + +.. code-block:: console + + host:~$ ssh-keygen -s user_ca -I root -n root \ + -V "YYYYMMDDHHMMSS:YYYYMMDDHHMMSS" \ + -O source-address=192.168.0.0/16 \ + -O clear \ + -O permit-pty \ + user_root_ed25519.pub diff --git a/source/security/common/build-securiphy.rsti b/source/security/common/build-securiphy.rsti new file mode 100644 index 000000000..63ff2a451 --- /dev/null +++ b/source/security/common/build-securiphy.rsti @@ -0,0 +1,57 @@ +Build securiPHY image +===================== + +Building an image requires a working Yocto build setup according to the +|yocto-ref-manual|. + +Building a Signed Image +----------------------- + +To build a signed provisioning image for the configuration of the device +which can boot from SD card or Serial Downloader, the ``DISTRO`` needs to +be set to |distro-provisioning-vendor| or |distro-provisioning|. +The main parts for the provisioning-image are the bootloader and the FIT-image, +which includes an initramfs with all necessary tools. + +.. code-block:: console + + # for NXP SoC + host:~$ bitbake phytec-provisioning-image + + # for TI K3 SoC + host:~$ bitbake phytec-headless-image + +To build the |image-secure-name| for the eMMC or ubifs with RAUC update support, +then the ``DISTRO`` needs to be set to |distro-secure-vendor| or +|distro-secure|. + +.. code-block:: console + :substitutions: + + # for all SoC + host:~$ bitbake |image-secure-name| + +.. note:: + If you have some boot warnings or errors like "/initrd.image: incomplete + write" or the kernel boot fails, then please check the size for Contiguous + Memory Allocation (CMA; kernel boot parameter, setting in bootloader). The + allocated RAM for CMA can be too much, which is important for systems with + 256 MiB or 512 MiB RAM. + +Configure the securiPHY build +----------------------------- + +Configuration options in the yocto build: + +* ``UBOOT_SIGN_ENABLE`` controls if the fitImage will be signed. The default is + ``1`` enabled. + +* The ``DISTROOVERRIDE secureboot`` enables security features and bootloader sigining + for NXP i.MX SoCs. To enable bootloader signing on TI K3 SoCs use a machine with + the ``MACHINEOVERRIDE secureenforced``. + +* ``DISTRO_FEATURE disable-console`` disables the u-boot and linux console. + +* ``DISTRO_FEATURE ssh-authentication`` requires ssh certificate authentication. + +* ``DISTRO_FEATURE ssh-hardening`` enables additional ssh hardening options. diff --git a/source/security/common/introduction.rsti b/source/security/common/introduction.rsti new file mode 100644 index 000000000..f63060c03 --- /dev/null +++ b/source/security/common/introduction.rsti @@ -0,0 +1,74 @@ +Introduction +============ + +PHYTEC's Yocto distribution securiPHY supports different security mechanism. The +security features have impact on the bootloader, the Linux kernel, Device Tree, +and root filesystem. This manual describes how security features are used and +implemented on various PHYTEC platforms. Note that different modules use +different bootloaders and flash storage devices, which affects the way things +are handled. Make sure to read the correct sections fitting your platform. + +Short Crypto Refresher +---------------------- + ++----------------------------+-----------------------------------------------------------+ +| Function | Description | ++============================+===========================================================+ +| Symmetric cryptography | The same key for encryption or decryption | ++----------------------------+-----------------------------------------------------------+ +| Public key cryptography | | Two mathematically dependent keys for encryption or | +| | | decryption. The public key is used for encryption while | +| | | the private key is used for decryption. | ++----------------------------+-----------------------------------------------------------+ +| Hash | One-way function, fixed output size (SHA*) | ++----------------------------+-----------------------------------------------------------+ +| HMAC | Data authentication using hash and shared secret | ++----------------------------+-----------------------------------------------------------+ +| Signature | | Data authentication using public-key cryptography | +| | | (keys & certificates, RSA & ECDSA) | ++----------------------------+-----------------------------------------------------------+ +| Unauthenticated encryption | | Attackers can‘t read private data but could modify it | +| | | (AES-CBC, AES-XTS, ...) | ++----------------------------+-----------------------------------------------------------+ +| Authenticated encryption | | Attacker can‘t read private data and modification is | +| | | detetcted (AEAD: AES GCM, AEGIS) | ++----------------------------+-----------------------------------------------------------+ +| Trusted Keys | | Symmetric key with variable length is a key type of the | +| | | existing kernel keyring service. | +| | | Require the availability of a Trust Source for greater | +| | | security like a TPM, NXP CAAM or TEE | ++----------------------------+-----------------------------------------------------------+ +| Encrypted Keys | | Symmetric key with variable length is a key type of the | +| | | existing kernel keyring service. | ++----------------------------+-----------------------------------------------------------+ + +Chain of Trust +-------------- + +Secure boot is used to ensure that only trustworthy, signed software can be +executed on the controller. This is the first stage of the Chain-of-Trust. +With the Chain-of-Trust, signed programs are always started by other previously +verified programs. This ensures that even the end application is at the +highest layer of trustworthiness. + +.. image:: images/chain-of-trust.jpg + +Phytec yocto distributions +-------------------------- + ++--------------------+-----------------------+------------------------------------+------------------------------+ +| | ampliphy | securiPHY-provisioning | securiPHY | ++====================+=======================+====================================+==============================+ +| Use case | early development || for production => provisioning || development with | +| | || initialize a device for the field || security focus | ++--------------------+-----------------------+------------------------------------+------------------------------+ +| Image | phytec-headless-image | phytec-provisioning-image | phytec-securiphy-image | ++--------------------+-----------------------+------------------------------------+------------------------------+ +| Update support | no | no | yes | ++--------------------+-----------------------+------------------------------------+------------------------------+ +| Secure boot chain | no | yes | yes | ++--------------------+-----------------------+------------------------------------+------------------------------+ +| serial console | yes | yes | no | ++--------------------+-----------------------+------------------------------------+------------------------------+ +| ssh access | root without password | root without password | root with client certificate | ++--------------------+-----------------------+------------------------------------+------------------------------+ diff --git a/source/security/common/key-management.rsti b/source/security/common/key-management.rsti new file mode 100644 index 000000000..9ab8d9bbf --- /dev/null +++ b/source/security/common/key-management.rsti @@ -0,0 +1,70 @@ +Using your own Keys and Certificates +==================================== + +See chapter |phytec-pki-link| to create your own keys and certificates for +secure boot. + +Key Settings in Yocto +--------------------- + +The created keys and certificates can be used in the yocto build by setting +specific variables. A list of all variables is in +``meta-ampliphy/classes/secureboot.bbclass`` +Set the variables corresponding to the used SoC in ``conf/local.conf`` of the +Yocto build directory. + +U-Boot signing +.............. + +NXP i.MX8MP using HABv4 +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + BOOTLOADER_SIGN_IMG_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem" + BOOTLOADER_SIGN_CSF_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem" + BOOTLOADER_SIGN_SRKFUSE_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/SRK_1_2_3_4_table.bin" + BOOTLOADER_HABV4_SRK_INDEX ??= "0 + +NXP i.MX91/93 using AHAB +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + AHAB_SRK_TABLE_BIN ?= "${CERT_PATH}/nxp_ahab_pki/crts/SRK_1_2_3_4_table.bin" + AHAB_SRK_PUB_CERT ?= "${CERT_PATH}/nxp_ahab_pki/crts/SRK1_sha512_secp521r1_v3_usr_crt.pem" + AHAB_SRK_INDEX ?= "0" + +TI K3 +~~~~~ + +.. code-block:: bash + + BOOTLOADER_TI_K3_MPK_KEY ??= "${CERT_PATH}/ti_k3/keys/phytecSMPK.pem" + BOOTLOADER_TI_K3_DEGENERATE_KEY ??= "${CERT_PATH}/ti_k3/keys/ti-degenerate-key.pem" + +FitImage signing +................ + +.. code-block:: bash + + UBOOT_SIGN_KEYDIR = "${CERT_PATH}/fit" + UBOOT_SIGN_KEYNAME = "FIT-4096" + UBOOT_SIGN_IMG_KEYNAME = "FIT-IMG-4096" + FIT_SIGN_ALG = "rsa4096" + FIT_HASH_ALG = "sha256" + +Kernel module signing +..................... + +.. code-block:: bash + + MODSIGN_KEY ?= "${CERT_PATH}/kernel_modsign/kernel_modsign.pem" + MODSIGN_CERT ?= "${CERT_PATH}/kernel_modsign/kernel_modsign.pem" + +SSH CA public key +................. + +.. code-block:: bash + + SSH_CA_PUBKEY ?= "${CERT_PATH}/ssh-ca/user-client-ca/user_client_ca.pub" diff --git a/source/security/common/provisioning-scripts.rsti b/source/security/common/provisioning-scripts.rsti new file mode 100644 index 000000000..3600e0279 --- /dev/null +++ b/source/security/common/provisioning-scripts.rsti @@ -0,0 +1,110 @@ +SecuriPHY Provisioning Scripts +=================================== + +The ``phytec-securiphy-image`` needs to be installed with the following provisioning +scripts. They are included in the ``phytec-provisioning-image``. + +phyprovisioning-install-emmc +---------------------------- + +The `phyprovisioning-install-emmc +`_ +script creates the partitions on the eMMC and installs bootloader and kernel. + +.. code-block:: console + + target:~$ phyprovisioning-install-emmc -h + + PHYTEC Install Script v0.7 for eMMC + + Usage: phyprovisioning-install-emmc [PARAMETER] [ACTION] + + Example: + phyprovisioning-install-emmc --filesystem /media/phytec-security-image.rootfs.partup --newemmc + + One of the following action can be selected: + -n | --newemmc Copy filesystem image to eMMC + + The following PARAMETER must be set for eMMC provisioning: + -p | --flashpath = /dev/mmcblk2 + -s | --filesystem + +physecurekeystorage-install +--------------------------- + +The `physecurekeystorage-install +`_ +tool initializes all supported secure key storages of your machine, but only one +can be active at a time. + +.. code-block:: console + + root@imx8mp-phyflex-libra-rdk-2:~# physecurekeystorage-install -h + + PHYTEC Install Script v1.7 for Secure Key Storage + + Usage: physecurekeystorage-install [PARAMETER] [ACTION] + + Example: + physecurekeystorage-install --newkeystorage trustedtpm + physecurekeystorage-install --deletekeystorage + physecurekeystorage-install --loadkeystorage + physecurekeystorage-install --pkcs11testkey + + One of the following action can be selected: + -n | --newkeystorage Create new Secure Key Storage + trustedcaam (only NXP controller) + trustedtee + trustedtpm + securecaam (black blob only NXP Vendor BSP) + -d | --deletekeystorage Erase the existing Secure Key Storage + -l | --loadkeystorage Load the existing Secure Key Storage + -p | --pkcs11testkey Create an ECC testkey with user pin 1234 + -h | --help This Help + -v | --version The version of physecurekeystorage-install + +physecurestorage-install +------------------------ + +The `physecurestorage-install +`_ +tool initializes the filesystem with encryption or integrity and encryption +combined. + +.. code-block:: console + + target:~$ physecurestorage-install -h + + PHYTEC Install Script v1.5 for Secure Storage + + Usage: physecurestorage-install [PARAMETER] [ACTION] + + Example: + physecurestorage-install --flashpath /dev/mmcblk0 + --filesystem /media/phytec-security-image.ext4 + --flashlayout 5,6 + --newsecurestorage intenc + + One of the following action can be selected: + -n | --newsecurestorage Create new Secure Storage of type + enc Encrypted root file system + intenc Encrypted root file system with integrity + -h | --help This Help + -v | --version The version of the physecurestorage-install + + The following PARAMETER must be set for new Secure Storage: + -p | --flashpath + -s | --filesystem + -l | --flashlayout partition number for the rootfs partitions + 5,6 rootfs partitions are 5 and 6 + -L | --labelname label name for the partition + +* The parameter is the eMMC device. +* The parameter is the path to the filesystem as tgz or ext4, + which should be installed on the flash device. +* Please copy the filesystem image, -.tar.gz, to a USB or + MMC drive so that it can be installed on the target. If partup packages are + used for initial flashing, then mount the partup package as type squashfs + first and find the root filesystem there. +* The parameter contains the rootfs partition numbers on the + target device. Set all partitions used for RAUC. diff --git a/source/security/common/provisioning.rsti b/source/security/common/provisioning.rsti new file mode 100644 index 000000000..70fad26ef --- /dev/null +++ b/source/security/common/provisioning.rsti @@ -0,0 +1,82 @@ +Provisioining +============= + +.. note:: + Create and use your own keys and certificates for signing your images. + Burn the right key into the Controller eFuse. + +Prepare Provisioning +-------------------- + +Flash the image ``phytec-provisioning-image-*.partup`` to the SD card using +partup. Set the boot mode to SD card according to the BSP manual for the used +board. Power the device and stop in the u-boot shell. + +Activate Secure Boot +-------------------- + +The first step to activate Secure Boot on your device is to burn the secure +eFuse configuration according to |activate-secureboot-link|. + +.. warning:: + + The secure eFuse configuration can only be written once and is irreversible! + +Provisioning the eMMC +--------------------- + +After the fuses are burned we can continue with provisioning the eMMC. Only the +eMMC should be used for the production image. +Boot into the provisioning image and log in as root. There is no password needed +at this point. Login over SSH is also possible. +The next three steps install the security image to the eMMC. The scripts are +already included in the provisioning image. More information about the +provisioning scripts is available in |provisioning-scripts-link|. + +phyprovisioning-install-emmc +............................ + +The tool ``phyprovisioning-install-emmc`` is used to initialize the eMMC and to +create all the required partitions. It requires the +``phytec-securiphy-image-*.partup`` package as input. Provide the file on the SD +card or through the network. + +.. code-block:: console + + target:~$ phyprovisioning-install-emmc \ + --filesystem /tmp/phytec-securiphy-image-phyboard-nash-imx93-1.rootfs.partup \ + --flashpath /dev/mmcblk0 \ + --newemmc + +This command also mounts the partup package at ``/media/data_partup``. + +physecurekeystorage-install +........................... + +The ``physecurekeystorage-install`` tool can initialize all supported secure key +storages of your machine, but only one can be active at a time. For example, +the phyBOARD Pollux i.MX8MP supports Trusted TEE, Trusted TPM, Trusted CAAM and +Secure CAAM, one of them has to be selected for the secure key storage. + +The following command creates the trusted and encrypted keys with Trusted TEE. + +.. code-block:: console + + target:~$ run0 physecurekeystorage-install --newkeystorage trustedtee + +physecurestorage-install +........................ + +The tool ``physecurestorage-install`` is used to create and populate the +encrypted filesystem. + +.. code-block:: console + + target:~$ run0 physecurestorage-install \ + --filesystem /media/data_partup/phytec-securiphy-image-phyboard-nash-imx93-1.rootfs.ext4 \ + --flashpath /dev/mmcblk0 \ + --flashlayout 5,6 \ + --newsecurestorage intenc + +The provisioning is now finished. Shutdown the provisioning system with +``shutdown 0`` and turn off the power to the device. diff --git a/source/security/common/recover-securiphy.rsti b/source/security/common/recover-securiphy.rsti new file mode 100644 index 000000000..15aa14dce --- /dev/null +++ b/source/security/common/recover-securiphy.rsti @@ -0,0 +1,8 @@ +Recover an Initialized Device +............................. + +If your filesystem is damaged or the key blob is deleted, then you can +reinstall the encrypted filesystem with the following options. + + 1. Reinitialize your device with the phytec-provisioning-image from the SD + card (Boot in initramfs) diff --git a/source/security/common/update-securiphy.rsti b/source/security/common/update-securiphy.rsti new file mode 100644 index 000000000..3e28a8a76 --- /dev/null +++ b/source/security/common/update-securiphy.rsti @@ -0,0 +1,31 @@ +Updating securiPHY +================== + +The update mechanism used in securiPHY is `RAUC +`_ (Robust Auto-Update Controller). The +|rauc-manual| describes how its integration and general +usage in the Phytec BSP. + +Build update bundle +------------------- + +The update bundle can be build with the command. + +.. code-block:: console + + host:~$ bitbake phytec-securiphy-bundle + +Migration Steps +--------------- + +Yocto scarthgap to walnascar or newer +..................................... + +The optee-client ``tee-supplicant`` uses a newly added user teesuppl. This user +has no access to data previously stored by optee in the config partition. + +There are 2 ways to fix this: + +1. Set optee client user back to root + +2. Change ownership of the optee data after the update diff --git a/source/security/head-sec.rst b/source/security/head-sec.rst deleted file mode 100644 index a3e478a19..000000000 --- a/source/security/head-sec.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. Download links -.. _`static-pdf-dl`: ../_static/head-sec.pdf - -.. |secure-boot-link| replace:: :ref:`secure-boot-head` -.. |secure-key-storage-link| replace:: :ref:`secure-key-storage-head` -.. |physical-security-link| replace:: :ref:`physical-security-head` -.. |phytec-pki-link| replace:: :ref:`phytec-pki-head` - -.. Yocto -.. |branding-name| replace:: securiPHY -.. |yocto-codename| replace:: Walnascar -.. |distro-secure-vendor| replace:: securiphy-vendor -.. |distro-secure| replace:: securiphy -.. |distro-provisioning| replace:: securiphy-provisioning -.. |distro-provisioning-vendor| replace:: securiphy-vendor-provisioning -.. |image-secure-name| replace:: phytec-securiphy-image - -.. only:: html - - Documentation in pdf format: `Download `_ - -+------------------+--------------+--------------+-----------+ -|| Compatible BSPs || BSP Release || BSP Release || Security | -|| || Type || Date || Support | -|| || || || Status | -+==================+==============+==============+===========+ -| | | | | -+------------------+--------------+--------------+-----------+ - -This manual applies to all |yocto-codename| based PHYTEC releases. - -Introduction -============ - -PHYTEC's Yocto distribution Securiphy (former Ampliphy-secure) supports -different security mechanism. The security features have impact on the -bootloader, the Linux kernel, Device Tree, and root filesystem. This manual -describes how security features are used and implemented on various PHYTEC -platforms. Note that different modules use different bootloaders and flash -storage devices, which affects the way things are handled. Make sure to -read the correct sections fitting your platform. - -.. note:: - - This manual contains machine-specific paths and variable contents. Make sure - you are using the correct machine and device names for your application when - executing any commands. - -.. _head-security-overview: -.. include:: common/security-overview.rsti - -.. include:: common/distro-using.rsti -.. _secure-boot-head: -.. include:: common/secure-boot.rsti -.. include:: common/activate-secureboot.rsti -.. include:: common/kernel-module-signing.rsti -.. include:: common/devicetree-overlay.rsti -.. _secure-key-storage-head: -.. include:: common/secure-key-storage.rsti -.. include:: common/secure-storage.rsti -.. include:: common/hardening.rsti -.. _physical-security-head: -.. include:: common/physical-security.rsti -.. _phytec-pki-head: -.. include:: common/phytec-pki.rsti -.. include:: common/vulnerabilities.rsti -.. include:: common/soc-configuration-tools.rsti diff --git a/source/security/manual-index.rst b/source/security/manual-index.rst index d3b46aa66..1994f1d6a 100644 --- a/source/security/manual-index.rst +++ b/source/security/manual-index.rst @@ -2,15 +2,15 @@ Security Manuals ================ -Head -==== +Walnascar +========= .. toctree:: :caption: Table of Contents :numbered: :maxdepth: 2 - head-sec + walnascar-sec Scarthgap ========= diff --git a/source/security/walnascar-sec.rst b/source/security/walnascar-sec.rst new file mode 100644 index 000000000..743a4fa8c --- /dev/null +++ b/source/security/walnascar-sec.rst @@ -0,0 +1,70 @@ +.. Download links +.. _`static-pdf-dl`: ../_static/walnascar-sec.pdf + +.. |secure-boot-link| replace:: :ref:`secure-boot-walnascar` +.. |activate-secureboot-link| replace:: :ref:`activate-secureboot-walnascar` +.. |secure-key-storage-link| replace:: :ref:`secure-key-storage-walnascar` +.. |physical-security-link| replace:: :ref:`physical-security-walnascar` +.. |phytec-pki-link| replace:: :ref:`phytec-pki-walnascar` +.. |provisioning-scripts-link| replace:: :ref:`provisioning-scripts-walnascar` + +.. Yocto +.. |branding-name| replace:: securiPHY +.. |yocto-codename| replace:: Walnascar +.. |distro-secure-vendor| replace:: securiphy-vendor +.. |distro-secure| replace:: securiphy +.. |distro-provisioning| replace:: securiphy-provisioning +.. |distro-provisioning-vendor| replace:: securiphy-vendor-provisioning +.. |image-secure-name| replace:: phytec-securiphy-image +.. |yocto-ref-manual| replace:: :ref:`Yocto Reference Manual ` +.. |rauc-manual| replace:: :ref:`Phytec RAUC Manual ` + +.. only:: html + + Documentation in pdf format: `Download `_ + ++--------------------------------+--------------+--------------+-----------+ +|| Compatible BSPs || BSP Release || BSP Release || Security | +|| || Type || Date || Support | +|| || || || Status | ++================================+==============+==============+===========+ +| BSP-Yocto-NXP-i.MX91-PD26.1.0 | Major | 2026-03-30 | full | ++--------------------------------+--------------+--------------+-----------+ +| BSP-Yocto-NXP-i.MX93-PD26.1.0 | Major | 2026-03-30 | full | ++--------------------------------+--------------+--------------+-----------+ +| BSP-Yocto-NXP-i.MX8MP-PD26.1.0 | Major | 2026-06-10 | full | ++--------------------------------+--------------+--------------+-----------+ + +This manual applies to all |yocto-codename| based PHYTEC releases. + +.. note:: + + This manual contains machine-specific paths and variable contents. Make sure + you are using the correct machine and device names for your application when + executing any commands. + +.. include:: common/introduction.rsti +.. include:: common/provisioning.rsti +.. include:: common/booting-securiphy.rsti +.. include:: common/key-management.rsti +.. include:: common/build-securiphy.rsti +.. include:: common/update-securiphy.rsti +.. _secure-boot-walnascar: +.. include:: common/secure-boot.rsti +.. _provisioning-scripts-walnascar: +.. include:: common/provisioning-scripts.rsti +.. _activate-secureboot-walnascar: +.. include:: common/activate-secureboot.rsti +.. include:: common/kernel-module-signing.rsti +.. include:: common/devicetree-overlay.rsti +.. _secure-key-storage-walnascar: +.. include:: common/secure-key-storage.rsti +.. include:: common/secure-storage.rsti +.. include:: common/recover-securiphy.rsti +.. include:: common/hardening.rsti +.. _physical-security-walnascar: +.. include:: common/physical-security.rsti +.. _phytec-pki-walnascar: +.. include:: common/phytec-pki.rsti +.. include:: common/vulnerabilities.rsti +.. include:: common/soc-configuration-tools.rsti