中文 EN

FBE File Encryption

Overview

This document introduces the X5 FBE feature, which is implemented based on file-level encryption in the Linux kernel.

Similar to FDE, X5-FBE automatically encrypts data when users write data and stores it into eMMC, and automatically decrypts data when users read from eMMC. The entire encryption/decryption process is transparent to users, who do not need to explicitly invoke encryption algorithms.

The difference is that FDE is disk-based encryption and can only protect an entire partition, whereas FBE can protect the contents of any specific directory. Moreover, FBE allows dynamic selection and encryption/decryption of individual files at runtime. Therefore, FBE is more flexible than FDE.

Abbreviation Full Name
FBE File Based Encryption

X5-FBE Usage

  • X5-FBE is based on fscrypt at the kernel layer. The source code is located at: kernel/fs/crypto.

Ensure the following configuration is enabled in the kernel. The configuration file is located at kernel/arch/arm64/configs. This has already been enabled on the D-Robotics X5-evb platform:

CONFIG_FS_ENCRYPTION=y

This tool is integrated into the X5 rootfs via Buildroot. After flashing the image, it can be used directly:

root@buildroot:~# fscryptctl -v
v1.0.0

The D-Robotics X5 platform supports using a derived key as the FBE key. The derived key is generated from a user root key. For more information about the user root key, refer to FDE.

  • Ensure the target partition has the encrypt feature enabled.

For example, all experiments below are performed under /userdata, so ensure the partition containing /userdata has the encrypt feature enabled:

root@buildroot:~# tune2fs -O encrypt /dev/block/platform/by-name/userdata
tune2fs 1.46.5 (30-Dec-2021)
root@buildroot:~# tune2fs -l /dev/block/platform/by-name/userdata | grep -i "Filesystem features"
Filesystem features:      has_journal ext_attr resize_inode dir_index filetype needs_recovery extent 64bit flex_bg encrypt sparse_super large_file huge_file dir_nlink extra_isize metadata_csum

  • By default, FBE uses kernel-provided CPU-based encryption algorithms.

In fscryptctl, the default algorithm for filename encryption is AES-256-CTS, and the default algorithm for file content encryption is AES-256-XTS. Ensure these two algorithms are enabled in the kernel:

CONFIG_CRYPTO_CTS=y
CONFIG_CRYPTO_XTS=y

Using External Key

# Initialize FBE
tune2fs -O encrypt /dev/block/platform/by-name/userdata
# Generate key
dd if=/dev/random of=/userdata/keyfile bs=1 count=32
mkdir -p /userdata/fbe
cd /userdata/fbe/
# Apply key to directory
fscryptctl add_key . < /userdata/keyfile > /userdata/keyid
# Set directory policy
fscryptctl set_policy $(cat /userdata/keyid) .
echo "test" > test.txt;
cat test.txt
# Remove the corresponding key
fscryptctl remove_key  $(cat /userdata/keyid) .
cat test.txt

Using X5 Derived Key

# Initialize FBE
tune2fs -O encrypt /dev/block/platform/by-name/userdata
mkdir -p /userdata/fbe
cd /userdata/fbe/
# Apply key to directory
getdmkey --km | xxd -r -p | fscryptctl add_key . > /userdata/keyid
# Set directory policy
fscryptctl set_policy $(cat /userdata/keyid) .
echo "test" > test.txt;
cat test.txt
# Remove the corresponding key
fscryptctl remove_key  $(cat /userdata/keyid) .
cat test.txt