Skip to content

feat(linux): Add fTPM based filesystem encryption rst #660

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shiva-ti wants to merge 1 commit into
base: master
Choose a base branch
from
+306 −2
Open

feat(linux): Add fTPM based filesystem encryption rst #660

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions configs/AM62AX/AM62AX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions configs/AM62LX/AM62LX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions configs/AM62PX/AM62PX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions configs/AM62X/AM62X_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
293 changes: 293 additions & 0 deletions source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,293 @@
.. _filesystem-encryption:

Check warning on line 1 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.ReadabilityGrade] Simplify your language. The calculated Flesch–Kincaid grade level of 11.11 is above the recommended reading grade level of 9.

Raw Output:
{"message": "[RedHat.ReadabilityGrade] Simplify your language. The calculated Flesch–Kincaid grade level of 11.11 is above the recommended reading grade level of 9.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 1, "column": 1}}}, "severity": "INFO"}

################################
File System Encryption with fTPM

Check warning on line 4 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'File System Encryption with fTPM'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'File System Encryption with fTPM'.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 4, "column": 1}}}, "severity": "INFO"}
################################

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

Check warning on line 13 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 13, "column": 56}}}, "severity": "INFO"}
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

Check warning on line 22 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 22, "column": 46}}}, "severity": "INFO"}
in OP-TEE to protect encryption keys, with secure persistent storage

Check warning on line 23 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TEE') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TEE') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 23, "column": 7}}}, "severity": "INFO"}
in TPM's persistent handles. The solution provides strong data-at-rest

Check warning on line 24 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 24, "column": 4}}}, "severity": "INFO"}
protection without requiring discrete TPM hardware.

Check warning on line 25 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 25, "column": 39}}}, "severity": "INFO"}

************
Key features
************

- **TPM-protected keys**: Firmware TPM generates and seals encryption

Check warning on line 31 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 31, "column": 36}}}, "severity": "INFO"}

Check warning on line 31 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 31, "column": 5}}}, "severity": "INFO"}
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

Check warning on line 36 in source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TPM') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst", "range": {"start": {"line": 36, "column": 20}}}, "severity": "INFO"}

********
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
<building-the-sdk-with-yocto>` as reference while following the below
steps specific to LUKS:

#. Use the latest :ref:`oe-config file <yocto-layer-configuration>`, 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_NAME>.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

10 changes: 8 additions & 2 deletions source/linux/Foundational_Components/System_Security/Security_overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | |
+-------------------------+-----------------------------------------------------------+--------------------------------------+


Expand All @@ -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')
Expand Down
Binary file added source/linux/Foundational_Components/System_Security/images/LUKS_ftpm.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions source/linux/Foundational_Components_Security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading