Enabling Adiantum

Adiantum is an encryption method designed for devices running Android 9 and higher whose CPUs lack AES instructions. If you are shipping an ARM-based device with ARMv8 Cryptography Extensions or an x86-based device with AES-NI, you should not use Adiantum. AES is faster on those platforms.

For devices lacking these AES CPU instructions, Adiantum provides encryption on your device with very little performance overhead. For benchmarking numbers, see the Adiantum paper. For the benchmarking source to run on your hardware, see the Adiantum source on GitHub.

To enable Adiantum on a device running Android 9 or higher, you need to make kernel changes and userspace changes.

Kernel changes

Adiantum is supported by the Android common kernels, version 4.9 and higher.

If your device's kernel doesn't already have Adiantum support, cherry-pick the changes listed below. If you're having trouble cherry-picking, devices using full-disk encryption (FDE) can exclude the fscrypt: patch.

Kernel version Crypto and fscrypt patches dm-crypt patch
4.19 4.19 kernel dm-crypt patch
4.14 4.14 kernel dm-crypt patch
4.9 4.9 kernel dm-crypt patch

Enable Adiantum in your kernel

After integrating the kernel changes, change your kernel config by adding the lines:

CONFIG_CRYPTO_ADIANTUM=y
CONFIG_DM_CRYPT=y

If your device uses file-based encryption (FBE) and a kernel version 5.1 or higher, also add:

CONFIG_FS_ENCRYPTION=y

If your device uses file-based encryption (FBE) and a kernel version 5.0 or lower, also add:

CONFIG_F2FS_FS_ENCRYPTION=y

To ensure good performance on a 32-bit ARM kernel, enable NEON instructions for the kernel:

CONFIG_CRYPTO_AES_ARM=y
CONFIG_CRYPTO_CHACHA20_NEON=y
CONFIG_CRYPTO_NHPOLY1305_NEON=y
CONFIG_KERNEL_MODE_NEON=y

Userspace changes

In Android 10 and higher, the userspace changes are already present.

For devices running Android 9, cherry-pick the Adiantum userspace changes in the userspace_adiantum_support_pie topic on the pie-platform-release branch in AOSP.

These changes are also in the master branch of AOSP.

Enable Adiantum in your device

Devices with file-based encryption

To enable Adiantum file-based encryption on your device's internal storage, set the appropriate fileencryption option for the userdata partition in the device's fstab:

fileencryption=adiantum

Next, if your device supports adoptable storage, also enable Adiantum encryption on adoptable storage. To do this, set the following properties in PRODUCT_PROPERTY_OVERRIDES:

For Android R and higher:

ro.crypto.volume.options=adiantum
ro.crypto.volume.metadata.encryption=adiantum

For Android 9 and 10:

ro.crypto.volume.contents_mode=adiantum
ro.crypto.volume.filenames_mode=adiantum
ro.crypto.fde_algorithm=adiantum
ro.crypto.fde_sector_size=4096

To verify that your implementation worked, take a bug report or run:

adb root
adb shell dmesg

If Adiantum is enabled correctly, you should see this in the kernel log:

fscrypt: Adiantum using implementation "adiantum(xchacha12-neon,aes-arm,nhpoly1305-neon)"

Starting with Android R, it is also possible to use Adiantum for metadata encryption on internal storage. See the metadata encryption documentation for details.

Devices with full-disk encryption

To enable Adiantum and improve its performance, set these properties in PRODUCT_PROPERTY_OVERRIDES:

ro.crypto.fde_algorithm=adiantum
ro.crypto.fde_sector_size=4096

Setting fde_sector_size to 4096 improves performance, but is not required for Adiantum to work. To use this setting, the userdata partition must begin at a 4096-byte aligned offset on-disk.

In the fstab, for userdata set:

forceencrypt

To verify that your implementation worked, take a bug report or run:

adb root
adb shell dmesg

If Adiantum is enabled correctly, you should see this in the kernel log:

device-mapper: crypt: adiantum(xchacha12,aes) using implementation "adiantum(xchacha12-neon,aes-arm,nhpoly1305-neon)"