phytec · landerweit-phytec · Jun 11, 2026 · May 19, 2026 · Apr 23, 2026 · Apr 23, 2026
@@ -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,

@@ -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

@@ -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
 --------------------------------
 
@@ -157,13 +114,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!                                |

@@ -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
+<https://github.com/phytec/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
@@ -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.
@@ -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"
-
@@ -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 |
++--------------------+-----------------------+------------------------------------+------------------------------+