Skip to content

Commit 0749309

Browse files
shiva-tishiva-ti
committed
feat(linux): Add fTPM based filesystem encryption rst
Add new security subsection for fTPM based filesystem encryption feature. Enable this documentation for AM62AX, AM62AX, AM62PX, AM62LX as per testing done with 12.0 SDK. Signed-off-by: Shiva Tripathi <s-tripathi1@ti.com>
1 parent fc6a7f3 commit 0749309

8 files changed

Lines changed: 304 additions & 0 deletions

File tree

‎configs/AM62AX/AM62AX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ linux/Foundational_Components/System_Security/Security_overview
9898
linux/Foundational_Components/System_Security/SELinux
9999
linux/Foundational_Components/System_Security/Auth_boot
100100
linux/Foundational_Components/System_Security/Memory_Firewalls
101+
linux/Foundational_Components/System_Security/Filesystem_Encryption
101102

102103
linux/Foundational_Components_Kernel_Users_Guide
103104
linux/Foundational_Components_Kernel_LTP-DDT_Validation

‎configs/AM62LX/AM62LX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ linux/Foundational_Components/System_Security/Security_overview
8484
#linux/Foundational_Components/System_Security/SELinux
8585
linux/Foundational_Components/System_Security/Auth_boot
8686
linux/Foundational_Components/System_Security/Memory_Firewalls
87+
linux/Foundational_Components/System_Security/Filesystem_Encryption
8788

8889
linux/Foundational_Components_Kernel_Users_Guide
8990
linux/Foundational_Components_Kernel_LTP-DDT_Validation

‎configs/AM62PX/AM62PX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ linux/Foundational_Components/System_Security/Security_overview
103103
linux/Foundational_Components/System_Security/SELinux
104104
linux/Foundational_Components/System_Security/Auth_boot
105105
linux/Foundational_Components/System_Security/Memory_Firewalls
106+
linux/Foundational_Components/System_Security/Filesystem_Encryption
106107

107108
linux/Foundational_Components_Kernel_Users_Guide
108109
linux/Foundational_Components_Kernel_LTP-DDT_Validation

‎configs/AM62X/AM62X_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ linux/Foundational_Components/System_Security/Security_overview
100100
linux/Foundational_Components/System_Security/SELinux
101101
linux/Foundational_Components/System_Security/Auth_boot
102102
linux/Foundational_Components/System_Security/Memory_Firewalls
103+
linux/Foundational_Components/System_Security/Filesystem_Encryption
103104

104105
linux/Foundational_Components_PRU_Subsystem
105106
linux/Foundational_Components/PRU-ICSS-Linux-Drivers

‎source/linux/Foundational_Components/System_Security/Filesystem_Encryption.rst‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
.. _filesystem-encryption:
2+
3+
################################
4+
File System Encryption with fTPM
5+
################################
6+
7+
************
8+
Introduction
9+
************
10+
11+
Data security is essential in modern embedded systems, be it industrial,
12+
automotive or IoT applications. This guide provides a reference
13+
implementation for root filesystem encryption by using TPM(Trusted Platform
14+
Module)-protected keys on TI K3 platforms.
15+
16+
**Yocto-Based Implementation:**
17+
18+
This is a Yocto based implementation integrated into the Processor SDK.
19+
It provides recipes and configuration for LUKS2 full-disk encryption
20+
with automatic first-boot encryption and following boots decryption,
21+
all controlled through Yocto recipes.
22+
The implementation here leverages a firmware TPM (fTPM) running
23+
in OP-TEE to protect encryption keys, with secure persistent storage
24+
in TPM's persistent handles. The solution provides strong data-at-rest
25+
protection without requiring discrete TPM hardware.
26+
27+
************
28+
Key features
29+
************
30+
31+
- **TPM-protected keys**: Firmware TPM generates and seals encryption
32+
keys during first boot
33+
- **Automatic In-place encryption**: First-boot encryption (in-place)
34+
and next boot decryption happen automatically
35+
- **Secure key storage**: Keys stored in TPM persistent storage
36+
accessed through TPM 2.0 APIs
37+
38+
********
39+
Concepts
40+
********
41+
42+
Root Filesystem Encryption
43+
==========================
44+
45+
Root filesystem encryption protects data at rest by encrypting the
46+
filesystem (root partition of SD card). This ensures that data
47+
cannot be accessed if the storage device is physically removed
48+
from the system.
49+
The Linux kernel uses **dm-crypt** (Device Mapper Crypt) to provide
50+
block-level encryption, with **LUKS** (Linux Unified Key Setup) managing
51+
encryption parameters and key slots.
52+
53+
Firmware TPM (fTPM)
54+
===================
55+
56+
A firmware TPM (fTPM) implements the TPM 2.0 specification as a
57+
Trusted Application running within OP-TEE's secure environment:
58+
59+
- **Key generation**: Creates cryptographically strong keys using
60+
hardware entropy
61+
- **Key sealing**: Protects keys so they can only be accessed in
62+
a known secure state
63+
- **Secure storage**: Stores TPM state in tamper-resistant eMMC RPMB
64+
65+
eMMC RPMB
66+
=========
67+
68+
Replay Protected Memory Block (RPMB) is a secure partition in eMMC storage:
69+
70+
- **Authentication**: Only accepts authenticated write operations
71+
- **Replay protection**: Prevents replay attacks with write counters
72+
- **Limited access**: Only accessible through OP-TEE secure environment
73+
74+
The fTPM stores its persistent state in eMMC RPMB through OP-TEE's secure
75+
backend.
76+
77+
**********************
78+
Implementation Details
79+
**********************
80+
81+
System Architecture
82+
===================
83+
84+
.. figure:: ./images/LUKS_ftpm.png
85+
86+
The filesystem encryption implementation consists of several components
87+
working together across the boot process:
88+
89+
- **Bootloader** : U-Boot loads kernel, initramfs and DTBs into memory
90+
from unencrypted boot partition
91+
- **Linux Kernel**: Provides the core cryptographic functionality through
92+
the Device Mapper subsystem
93+
- **Initramfs**: Contains the early boot environment where
94+
encryption/decryption occurs
95+
- **OP-TEE**: Secure operating system running in TrustZone that hosts the
96+
firmware TPM
97+
- **eMMC Storage**: provides tamper-resistant key storage with RPMB
98+
99+
Boot Process Flow
100+
=================
101+
102+
The encryption system operates during the Linux boot process:
103+
104+
#. **Bootloader Stage**: U-boot loads the kernel and initramfs into memory
105+
#. **Early Boot**: The kernel starts and mounts the initramfs as a
106+
temporary root filesystem
107+
#. **TPM Initialization**: The firmware TPM is initialized within OP-TEE
108+
#. **Encryption Detection**: The system checks if the root partition is
109+
already encrypted
110+
#. **Encryption/Decryption**: Based on the detection result, the system
111+
either:
112+
113+
- Performs first-time in-place encryption of the root filesystem
114+
- Retrieves the key from TPM and decrypts the existing encrypted filesystem
115+
#. **Root Switch**: Control is transferred to the actual root filesystem
116+
117+
Key Management Flow
118+
===================
119+
120+
The encryption key lifecycle is managed securely:
121+
122+
#. **Key Generation**: During first boot, the TPM generates a random
123+
encryption key
124+
#. **Key Sealing**: The key is sealed by the TPM, protecting it from
125+
unauthorized access
126+
#. **Key Storage**: Sealed key data is stored in eMMC RPMB through the
127+
TPM's secure storage
128+
#. **Key Retrieval**: During later boots, the key is unsealed by
129+
the TPM
130+
131+
Encryption Process
132+
==================
133+
134+
The in-place encryption process follows these steps:
135+
136+
#. **Filesystem Preparation**: The filesystem is checked and resized to
137+
make room for LUKS headers
138+
#. **Space Verification**: The system ensures at least 32MB is available
139+
for LUKS metadata
140+
#. **Encryption Initialization**: LUKS headers are written to the beginning
141+
of the partition
142+
#. **Block Encryption**: Data blocks are read, encrypted, and written back
143+
to storage
144+
#. **Filesystem Expansion**: After encryption, the filesystem is expanded
145+
to use available space
146+
147+
*****
148+
Setup
149+
*****
150+
151+
The fTPM based filesystem encryption support is available in Yocto. The
152+
following section acts as the guide for setting it up.
153+
Please use :ref:`Processor SDK - Building the SDK with Yocto
154+
<building-the-sdk-with-yocto>` as reference while following the below
155+
steps specific to LUKS:
156+
157+
#. Use the latest :ref:`oe-config file <yocto-layer-configuration>`, using
158+
the "luks" specific config.
159+
#. Before building the SDK image, there are few **prerequisites**:
160+
161+
- **Writing keys to eMMC RPMB** : The implementation here uses RPMB keys
162+
for secure persitance storage. Writing keys into RPMB is a one-time
163+
and non-reversible step, follow :ref:`secure-storage-with-rpmb`
164+
- Once the keys are written to RPMB, the optee-os and optee-client
165+
components in yocto setup should be configured to make use of these
166+
hardware keys.
167+
Following can be used in yocto for the same:
168+
169+
- for **optee-os**: under meta-ti layer:
170+
*"meta-ti-bsp/recipes-security/optee/optee-os-ti-overrides.inc"*
171+
172+
.. code-block:: console
173+
174+
EXTRA_OEMAKE:append:k3 = " \
175+
CFG_REE_FS=n \
176+
CFG_RPMB_FS=y \
177+
CFG_RPMB_WRITE_KEY=y \
178+
CFG_RPMB_ANNOUNCE_PROBE_CAP=n \
179+
"
180+
181+
- for **optee-client**: disable RPMB emulation mode. under meta-ti layer:
182+
*"meta-ti-bsp/recipes-security/optee/optee-client_%.bbappend"*
183+
184+
.. code-block:: console
185+
186+
EXTRA_OECMAKE:append = " -DRPMB_EMU=OFF"
187+
188+
- **u-boot configuration**: The kernel Image and dtbs are read from the
189+
root partition of SD by default. But since this implemenation encrypts the root
190+
filesystem, u-boot needs to be configured to pick kernel image, dtbs
191+
and initramfs from the boot partition. This can be done using such
192+
following change in uboot (can be a patch in u-boot meta-ti layer):
193+
194+
.. ifconfig:: CONFIG_part_variant in ('AM62LX')
195+
196+
.. code-block:: console
197+
198+
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"
199+
200+
201+
.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
202+
203+
.. code-block:: console
204+
205+
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"
206+
207+
208+
- **Additional configs**: The following can be added in local.conf of yocto build:
209+
210+
- To copy dtbs to boot patition for post encryption boot:
211+
212+
.. code-block:: console
213+
214+
IMAGE_BOOT_FILES:append = " *.dtb"
215+
216+
- Adding free space in rootfs for LUKS encryption (since LUKS expects
217+
atleast 32MB of free space for header post resize2fs operations):
218+
219+
.. code-block:: console
220+
221+
IMAGE_ROOTFS_EXTRA_SPACE = "65536"
222+
223+
- Some other useful configurations (**not mandatory** to have):
224+
225+
- In order to use tpm2 tools in Linux command line, add following in
226+
local.conf:
227+
228+
.. code-block:: console
229+
230+
IMAGE_INSTALL:append = " \
231+
tpm2-tools \
232+
tpm2-tss \
233+
libtss2-tcti-device \
234+
"
235+
236+
- Size of initramfs image can be reduced by using the busybox
237+
optimizations, for reference:
238+
239+
.. code-block:: console
240+
241+
VIRTUAL-RUNTIME_init_manager:pn-packagegroup-ti-core-initramfs = "busybox"
242+
VIRTUAL-RUNTIME_dev_manager:pn-packagegroup-ti-core-initramfs = "busybox"
243+
244+
********************
245+
dm-crypt performance
246+
********************
247+
248+
- The first boot involves encryption of complete root filesystem using the
249+
ARM aes-generic (software implmentation), giving around 17.0 MB/s of
250+
performance. This makes use of "cryptsetup reencrypt" which reads,
251+
encrypts and writes back data. Therefore, the first boot is expected
252+
to take more time dependending on the size of filesystem.
253+
- The next boots involve decryption of data, giving around 86 MB/s
254+
of decryption throughput.
255+
256+
***********************
257+
Security Considerations
258+
***********************
259+
260+
Reference Implementation
261+
========================
262+
263+
This implementation serves as a reference design that demonstrates the
264+
integration of filesystem encryption with firmware TPM. It is **not intended
265+
for direct use in production environments without appropriate security
266+
review** and customization including:
267+
268+
- **Threat model evaluation**: a thorough threat assessment should be
269+
conducted before deployment
270+
- **Key management**: The default TPM persistent handle (0x81080001)
271+
should be reviewed for security requirements
272+
- **Boot process hardening**: The initramfs module may need modifications
273+
to align with specific security policies
274+
- **Recovery mechanisms**: Production implementations may require key
275+
recovery procedures
276+
277+
Further Enhancements
278+
====================
279+
280+
Implementation of this reference design can have following enhancements:
281+
282+
- **Integrating with secure boot**: Establish a verified chain of trust
283+
from ROM to filesystem
284+
- **Passphrase Recovery**: Incase the TPM keys become inaccessible during
285+
boot, the current implementation doesn't use any backup passphrase
286+
recovery method resulting in **potential data loss**. Using a passphrase
287+
would reduce risk of data loss but introduces additional security
288+
considerations.
289+
- **Measured boot**: Add TPM PCR measurements to bind keys to verified
290+
software state, the current reference doesn't use PCR measurements
291+
- **Audit logging**: Add secure logging of encryption/decryption
292+
operations for compliance purposes
293+

‎source/linux/Foundational_Components/System_Security/Security_overview.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ The following table lists some of the key Security Features:
6464
| **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` |
6565
| | security boundaries | |
6666
+-------------------------+-----------------------------------------------------------+--------------------------------------+
67+
|**fTPM based** | Yocto reference implemenation of filesystem encryption | :ref:`filesystem-encryption` |
68+
|**Filesystem Encryption**| using LUKS2 with TPM-sealed keys | |
69+
+-------------------------+-----------------------------------------------------------+--------------------------------------+
6770

6871

6972
.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62PX', 'AM62AX')
@@ -90,6 +93,9 @@ The following table lists some of the key Security Features:
9093
| **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` |
9194
| | security boundaries | |
9295
+-------------------------+-----------------------------------------------------------+--------------------------------------+
96+
|**fTPM based** | Yocto reference implemenation of filesystem encryption | :ref:`filesystem-encryption` |
97+
|**Filesystem Encryption**| using LUKS2 with TPM-sealed keys | |
98+
+-------------------------+-----------------------------------------------------------+--------------------------------------+
9399

94100
.. ifconfig:: CONFIG_part_variant not in ('AM62X', 'AM62PX', 'AM62AX', 'AM62LX')
95101

‎source/linux/Foundational_Components/System_Security/images/LUKS_ftpm.png‎

185 KB
Loading

‎source/linux/Foundational_Components_Security.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ Security
1313
Foundational_Components/System_Security/SELinux
1414
Foundational_Components/System_Security/Auth_boot
1515
Foundational_Components/System_Security/Memory_Firewalls
16+
Foundational_Components/System_Security/Filesystem_Encryption

0 commit comments

Comments
 (0)