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/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 diff --git a/source/security/common/activate-secureboot.rsti b/source/security/common/activate-secureboot.rsti index 93cfe0db1..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 -------------------------------- @@ -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! | 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/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" - 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/phytec-pki.rsti b/source/security/common/phytec-pki.rsti index 255ea1465..b911d478d 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. @@ -134,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 ----------------- @@ -523,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 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/secure-boot.rsti b/source/security/common/secure-boot.rsti index 4b9f51de9..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 @@ -73,155 +74,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/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/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/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/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 6920e8d3d..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/kirkstone-sec.rst b/source/security/kirkstone-sec.rst index 1d1bfd389..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 ================================== @@ -703,6 +753,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/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/scarthgap-sec.rst b/source/security/scarthgap-sec.rst index 4b47100f8..bba9004ad 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 @@ -86,12 +86,281 @@ 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 .. _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 + +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 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