diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt index 4d3f9ce8c..560f8ed91 100644 --- a/configs/AM62AX/AM62AX_linux_toc.txt +++ b/configs/AM62AX/AM62AX_linux_toc.txt @@ -98,6 +98,7 @@ linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot linux/Foundational_Components/System_Security/Memory_Firewalls +linux/Foundational_Components/System_Security/Filesystem_Encryption linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62LX/AM62LX_linux_toc.txt b/configs/AM62LX/AM62LX_linux_toc.txt index b9e69e127..369b8207c 100644 --- a/configs/AM62LX/AM62LX_linux_toc.txt +++ b/configs/AM62LX/AM62LX_linux_toc.txt @@ -84,6 +84,7 @@ linux/Foundational_Components/System_Security/Security_overview #linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot linux/Foundational_Components/System_Security/Memory_Firewalls +linux/Foundational_Components/System_Security/Filesystem_Encryption linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt index eff335a52..4d73e5f02 100644 --- a/configs/AM62PX/AM62PX_linux_toc.txt +++ b/configs/AM62PX/AM62PX_linux_toc.txt @@ -103,6 +103,7 @@ linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot linux/Foundational_Components/System_Security/Memory_Firewalls +linux/Foundational_Components/System_Security/Filesystem_Encryption linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt index 96e533da1..52d109bc6 100644 --- a/configs/AM62X/AM62X_linux_toc.txt +++ b/configs/AM62X/AM62X_linux_toc.txt @@ -100,6 +100,7 @@ linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot linux/Foundational_Components/System_Security/Memory_Firewalls +linux/Foundational_Components/System_Security/Filesystem_Encryption linux/Foundational_Components_PRU_Subsystem linux/Foundational_Components/PRU-ICSS-Linux-Drivers diff --git a/source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst b/source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst new file mode 100644 index 000000000..ef8aa8f75 --- /dev/null +++ b/source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst @@ -0,0 +1,293 @@ +.. _filesystem-encryption: + +################################ +File System Encryption with fTPM +################################ + +************ +Introduction +************ + +Data security is essential in modern embedded systems, be it industrial, +automotive or IoT applications. This guide provides a reference +implementation for root filesystem encryption by using TPM (Trusted Platform +Module)-protected keys on TI K3 platforms. + +**Yocto-Based Implementation:** + +This is a Yocto based implementation integrated into the Processor SDK. +It provides recipes and configuration for LUKS2 full-disk encryption +with automatic first-boot encryption and following boots decryption, +all controlled through Yocto recipes. +The implementation here leverages a firmware TPM (fTPM) running +in OP-TEE to protect encryption keys, with secure persistent storage +in TPM's persistent handles. The solution provides strong data-at-rest +protection without requiring discrete TPM hardware. + +************ +Key features +************ + +- **TPM-protected keys**: Firmware TPM generates and seals encryption + keys during first boot +- **Automatic In-place encryption**: First-boot encryption (in-place) + and next boot decryption happen automatically +- **Secure key storage**: Keys stored in TPM persistent storage + accessed through TPM 2.0 APIs + +******** +Concepts +******** + +Root Filesystem Encryption +========================== + +Root filesystem encryption protects data at rest by encrypting the +filesystem (root partition of SD card). This ensures that data +cannot be accessed if the storage device is physically removed +from the system. +The Linux kernel uses **dm-crypt** (Device Mapper Crypt) to provide +block-level encryption, with **LUKS** (Linux Unified Key Setup) managing +encryption parameters and key slots. + +Firmware TPM (fTPM) +=================== + +A firmware TPM (fTPM) implements the TPM 2.0 specification as a +Trusted Application running within OP-TEE's secure environment: + +- **Key generation**: Creates cryptographically strong keys using + hardware entropy +- **Key sealing**: Protects keys so they can only be accessed in + a known secure state +- **Secure storage**: Stores TPM state in tamper-resistant eMMC RPMB + +eMMC RPMB +========= + +Replay Protected Memory Block (RPMB) is a secure partition in eMMC storage: + +- **Authentication**: Only accepts authenticated write operations +- **Replay protection**: Prevents replay attacks with write counters +- **Limited access**: Only accessible through OP-TEE secure environment + +The fTPM stores its persistent state in eMMC RPMB through OP-TEE's secure +backend. + +********************** +Implementation Details +********************** + +System Architecture +=================== + +.. figure:: ./images/LUKS_ftpm.png + +The filesystem encryption implementation consists of several components +working together across the boot process: + +- **Boot loader** : U-Boot loads kernel, initramfs and DTBs into memory + from unencrypted boot partition +- **Linux Kernel**: Provides the core cryptographic functionality through + the Device Mapper subsystem +- **Initramfs**: Contains the early boot environment where + encryption/decryption occurs +- **OP-TEE**: Secure operating system running in TrustZone that hosts the + firmware TPM +- **eMMC Storage**: provides tamper-resistant key storage with RPMB + +Boot Process Flow +================= + +The encryption system operates during the Linux boot process: + +#. **Boot loader Stage**: U-boot loads the kernel and initramfs into memory +#. **Early Boot**: The kernel starts and mounts the initramfs as a + temporary root filesystem +#. **TPM Initialization**: The firmware TPM is initialized within OP-TEE +#. **Encryption Detection**: The system checks if the root partition is + already encrypted +#. **Encryption/Decryption**: Based on the detection result, the system + either: + + - Performs first-time in-place encryption of the root filesystem + - Retrieves the key from TPM and decrypts the existing encrypted filesystem +#. **Root Switch**: Control is transferred to the actual root filesystem + +Key Management Flow +=================== + +The encryption key lifecycle is managed securely: + +#. **Key Generation**: During first boot, the TPM generates a random + encryption key +#. **Key Sealing**: The key is sealed by the TPM, protecting it from + unauthorized access +#. **Key Storage**: Sealed key data is stored in eMMC RPMB through the + TPM's secure storage +#. **Key Retrieval**: During later boots, the key is unsealed by + the TPM + +Encryption Process +================== + +The in-place encryption process follows these steps: + +#. **Filesystem Preparation**: The filesystem is checked and resized to + make room for LUKS headers +#. **Space Verification**: The system ensures at least 32MB is available + for LUKS metadata +#. **Encryption Initialization**: LUKS headers are written to the beginning + of the partition +#. **Block Encryption**: Data blocks are read, encrypted, and written back + to storage +#. **Filesystem Expansion**: After encryption, the filesystem is expanded + to use available space + +***** +Setup +***** + +The fTPM based filesystem encryption support is available in Yocto. The +following section acts as the guide for setting it up. +Please use :ref:`Processor SDK - Building the SDK with Yocto +` as reference while following the below +steps specific to LUKS: + +#. Use the latest :ref:`oe-config file `, using + the "luks" specific config. +#. Before building the SDK image, there are few **prerequisites**: + + - **Writing keys to eMMC RPMB** : The implementation here uses RPMB keys + for secure persitance storage. Writing keys into RPMB is a one-time + and non-reversible step, follow :ref:`secure-storage-with-rpmb` + - Once the keys are written to RPMB, the optee-os and optee-client + components in yocto setup should be configured to make use of these + hardware keys. + Following can be used in yocto for the same: + + - for **optee-os**: under meta-ti layer: + *"meta-ti-bsp/recipes-security/optee/optee-os-ti-overrides.inc"* + + .. code-block:: console + + EXTRA_OEMAKE:append:k3 = " \ + CFG_REE_FS=n \ + CFG_RPMB_FS=y \ + CFG_RPMB_WRITE_KEY=y \ + CFG_RPMB_ANNOUNCE_PROBE_CAP=n \ + " + + - for **optee-client**: disable RPMB emulation mode. under meta-ti layer: + *"meta-ti-bsp/recipes-security/optee/optee-client_%.bbappend"* + + .. code-block:: console + + EXTRA_OECMAKE:append = " -DRPMB_EMU=OFF" + + - **u-boot configuration**: The kernel Image and dtbs are read from the + root partition of SD by default. But since this implemenation encrypts the root + filesystem, u-boot needs to be configured to pick kernel image, dtbs + and initramfs from the boot partition. This can be done using such + following change in uboot (can be a patch in u-boot meta-ti layer): + + .. ifconfig:: CONFIG_part_variant in ('AM62LX') + + .. code-block:: console + + CONFIG_BOOTCOMMAND="setenv bootargs console=ttyS0,115200n8 earlycon=ns16550a,mmio32,0x02800000 root=/dev/mmcblk1p2 rootwait rootfstype=ext4; load mmc 1:1 0x82000000 /Image; load mmc 1:1 0x88080000 /ti-core-initramfs.cpio.xz; setenv initrd_size ${filesize}; load mmc 1:1 0x88000000 /k3-am62l3-evm.dtb; booti 0x82000000 0x88080000:${initrd_size} 0x88000000" + + + .. ifconfig:: CONFIG_part_variant not in ('AM62LX') + + .. code-block:: console + + CONFIG_BOOTCOMMAND="setenv bootargs console=ttyS2,115200n8 earlycon=ns16550a,mmio32,0x02800000 root=/dev/mmcblk1p2 rootwait rootfstype=ext4; load mmc 1:1 0x82000000 /Image; load mmc 1:1 0x88080000 /ti-core-initramfs.cpio.xz; setenv initrd_size ${filesize}; load mmc 1:1 0x88000000 /.dtb; booti 0x82000000 0x88080000:${initrd_size} 0x88000000" + + + - **Additional configs**: The following can be added in local.conf of yocto build: + + - To copy dtbs to boot patition for post encryption boot: + + .. code-block:: console + + IMAGE_BOOT_FILES:append = " *.dtb" + + - Adding free space in rootfs for LUKS encryption (since LUKS expects + atleast 32MB of free space for header post resize2fs operations): + + .. code-block:: console + + IMAGE_ROOTFS_EXTRA_SPACE = "65536" + +- Some other useful configurations (**not mandatory** to have): + + - In order to use tpm2 tools in Linux command line, add following in + local.conf: + + .. code-block:: console + + IMAGE_INSTALL:append = " \ + tpm2-tools \ + tpm2-tss \ + libtss2-tcti-device \ + " + + - Size of initramfs image can be reduced by using the busybox + optimizations, for reference: + + .. code-block:: console + + VIRTUAL-RUNTIME_init_manager:pn-packagegroup-ti-core-initramfs = "busybox" + VIRTUAL-RUNTIME_dev_manager:pn-packagegroup-ti-core-initramfs = "busybox" + +******************** +dm-crypt performance +******************** + +- The first boot involves encryption of complete root filesystem using the + ARM aes-generic (software implmentation), giving around 17.0 MB/s of + performance. This makes use of "cryptsetup reencrypt" which reads, + encrypts and writes back data. Therefore, the first boot is expected + to take more time dependending on the size of filesystem. +- The next boots involve decryption of data, giving around 86 MB/s + of decryption throughput. + +*********************** +Security Considerations +*********************** + +Reference Implementation +======================== + +This implementation serves as a reference design that demonstrates the +integration of filesystem encryption with firmware TPM. It is **not intended +for direct use in production environments without appropriate security +review** and customization including: + +- **Threat model evaluation**: a thorough threat assessment should be + conducted before deployment +- **Key management**: The default TPM persistent handle (0x81080001) + should be reviewed for security requirements +- **Boot process hardening**: The initramfs module may need modifications + to align with specific security policies +- **Recovery mechanisms**: Production implementations may require key + recovery procedures + +Further Enhancements +==================== + +Implementation of this reference design can have following enhancements: + +- **Integrating with secure boot**: Establish a verified chain of trust + from ROM to filesystem +- **Passphrase Recovery**: Incase the TPM keys become inaccessible during + boot, the current implementation doesn't use any backup passphrase + recovery method resulting in **potential data loss**. Using a passphrase + would reduce risk of data loss but introduces additional security + considerations. +- **Measured boot**: Add TPM PCR measurements to bind keys to verified + software state, the current reference doesn't use PCR measurements +- **Audit logging**: Add secure logging of encryption/decryption + operations for compliance purposes + diff --git a/source/linux/Foundational_Components/System_Security/Security_overview.rst b/source/linux/Foundational_Components/System_Security/Security_overview.rst index 14867038f..485a311c9 100644 --- a/source/linux/Foundational_Components/System_Security/Security_overview.rst +++ b/source/linux/Foundational_Components/System_Security/Security_overview.rst @@ -62,7 +62,10 @@ The following table lists some of the key Security Features: | | execution of security-sensitive applications and services | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ | **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` | - | | security boundaries | | + | | security boundaries | | + +-------------------------+-----------------------------------------------------------+--------------------------------------+ + |**fTPM based** | Yocto reference implemenation of filesystem encryption | :ref:`filesystem-encryption` | + |**Filesystem Encryption**| using LUKS2 with TPM-sealed keys | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ @@ -88,7 +91,10 @@ The following table lists some of the key Security Features: | | execution of security-sensitive applications and services | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ | **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` | - | | security boundaries | | + | | security boundaries | | + +-------------------------+-----------------------------------------------------------+--------------------------------------+ + |**fTPM based** | Yocto reference implemenation of filesystem encryption | :ref:`filesystem-encryption` | + |**Filesystem Encryption**| using LUKS2 with TPM-sealed keys | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ .. ifconfig:: CONFIG_part_variant not in ('AM62X', 'AM62PX', 'AM62AX', 'AM62LX') diff --git a/source/linux/Foundational_Components/System_Security/images/LUKS_ftpm.png b/source/linux/Foundational_Components/System_Security/images/LUKS_ftpm.png new file mode 100644 index 000000000..d34dc802d Binary files /dev/null and b/source/linux/Foundational_Components/System_Security/images/LUKS_ftpm.png differ diff --git a/source/linux/Foundational_Components_Security.rst b/source/linux/Foundational_Components_Security.rst index 904f03020..b120e17a2 100644 --- a/source/linux/Foundational_Components_Security.rst +++ b/source/linux/Foundational_Components_Security.rst @@ -13,3 +13,4 @@ Security Foundational_Components/System_Security/SELinux Foundational_Components/System_Security/Auth_boot Foundational_Components/System_Security/Memory_Firewalls + Foundational_Components/System_Security/Filesystem_Encryption