AN12714
AN12714
Contents
1 Preface 1 Preface............................................ 1
1.1 Intended audience and scope......1
Devices often contain highly sensitive information which is consistently at risk
1.2 References...................................1
to get physically lost or stolen. Setting user passwords does not guarantee data
2 Overview......................................... 1
protection against unauthorized access. The attackers can simply bypass the 2.1 DM-Crypt......................................1
software system of a device and access the data storage directly. Only the 2.2 DM-Crypt accelerated by CAAM
use of encryption can guarantee data confidentiality in the case where storage ..................................................... 2
media is directly accessed. 2.3 DM-Crypt using CAAM's Secure
Key...............................................3
This document provides steps to run a transparent storage encryption at block
3 Hands-On........................................ 4
level using DM-Crypt taking advantage of the secure key feature provided
3.1 Installation....................................4
by i.MXs Cryptographic Accelerator and Assurance Module (CAAM). The 3.2 Usage...........................................6
document applies to all i.MX SoCs having CAAM module. The feature is not 3.3 Performance................................ 9
available on i.MX SoCs with DCP. 4 Revision history............................. 10
5 Appendix A. Configuration............ 10
5.1 Kernel configuration................... 10
1.1 Intended audience and scope
This document is intended for software, hardware, and system engineers who are planning to use CAAM to perform
storage encryption.
1.2 References
• i.MX 8MM Security Reference Manual
• Linux mainline kernel archive, 2018.
• DM-Crypt: Linux device-mapper crypto target, 2018
• LUKS: Linux Unified Key Setup, 2018
• dmsetup(8) - Linux man page
• keyctl(1) - Linux man page
• keyrings - in-kernel key management and retention facilit
2 Overview
2.1 DM-Crypt
DM-Crypt is a Linux kernel module which provides disk encryption. The module takes advantage of the Linux kernel’s
device-mapper infrastructure and offers a wide range of use cases. It can run on a variety of storage block devices, even if these
devices use RAID and LVM. The device mapper is designed to provide a general and flexible way to add virtual layers over the
actual block device so that developers can implement mirroring, snapshot, cascade, and encryption.
DM-Crypt is implemented as a device mapper target and resides entirely in kernel space between Linux subsystem and actual
physical block device driver. This block device driver intercepts the request to read and write with the bio parameter that is sent to
the actual physical device driver, encrypts the data by using the crypto API provided by the kernel, and then writes the data back
to the actual block device. Figure 1 represents the overall architecture of DM-Crypt.
NXP Semiconductors
Overview
DM-Crypt supports the dynamic encryption function. Dynamic encryption, also called real-time encryption, or transparent
encryption, automatically encrypts or decrypts the data in the process of using without users’ intervention. The legitimate users
can use the encrypted files without explicitly performing decryption.
# cat /proc/crypto
name : cbc(aes)
driver : cbc-aes-caam
module : kernel
priority : 3000
refcnt : 1
selftest : passed
internal : no
type : skcipher
async : yes
blocksize : 16
min keysize : 16
max keysize : 32
ivsize : 16
chunksize : 16
walksize : 16
If there is more than one implementation for a specific transformation, DM-Crypt selects the implementation with higher priority.
i.MX SoCs provide modular and scalable hardware encryption through NXPs CAAM. To have DM-Crypt accelerated by CAAM,
the driver should register a transformation implementation with a higher priority.
In the output above, there are 2 implementations of cbc(aes) transformation. The CAAM-backed implementation has a priority of
3000 while the software implementation has a value of 300. This means that if you instruct DM-Crypt to use cbc(aes) cipher, the
CAAM-backed implementation is used.
To list all transformations registered by CAAM driver:
NOTE
AES in XTS mode is not supported on i.MX devices.
Dmsetup (part of the libdevmapper package) is a powerful tool for performing very low-level configuration and is used to manage
encrypted volumes instead of cryptsetup. Cryptsetup supports different encryption operating modes including plain mode and
LUKS mode which are the most common modes. In LUKS mode, the master-key is encrypted. While in plain mode, there is no
key encryption, yet passphrase hashing is not needed since secure key provides the same level of security. Hence, managing
encrypted devices using cryptsetup is not applicable and dmsetup is used instead.
3 Hands-On
The steps described in this section have been executed on a x86_64 machine running Ubuntu 16.04 for any host related actions
(for example, building) and on an i.MX 8MM-EVK board as a target device. This applies also to all i.MX devices having CAAM
module and running a block-based storage. NAND flash is an MTD device, hence, DM-Crypt cannot be used with it and the
hands-on do not apply for it.
3.1 Installation
1. Install the essential packages on your host machine.
$ sudo apt-get install gawk wget git-core diffstat unzip texinfo \ build-essential chrpath
libsdl1.2-dev xterm curl
$ mkdir -p ~/bin
$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo >\ ~/bin/repo
$ export PATH=$PATH:~/bin
$ chmod a+x ~/bin/repo
$ mkdir imx-yocto-bsp
$ cd imx-yocto-bsp
$ repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-zeus -m
imx-5.4.47-2.2.0.xml
$ repo sync
5. See Appendix A. Configuration for all the necessary kernel configurations that have to be enabled.
6. If not already installed, add the required tools to build by editing the conf/local.conf file and appending.
GNU’s dd is required instead of Busybox’s dd later for benchmarking. Keyutils provides keyctl, which is required to
manage Linux Key retention service.
Lvm2 provides dmsetup utility and libraries to manage device-mapper.
e2fsprogs-mke2fs contains necessary tools to create filesystems.
util-linux provides blockdev utility needed to read number of sectors from a volume.
7. Build.
$ bitbake core-image-base
$ cd tmp/deploy/images/imx8mmevk
$ bunzip2 -dk -f core-image-base-imx8mmevk.wic.bz2
$ sudo dd if=core-image-base-imx8mmevk.wic of=/dev/sd<partition> bs=1M conv=fsync
9. Build the user space application used to generate black keys and blobs and copy it to the device. The source code
can be found at https://source.codeaurora.org/external/imx/keyctl_caam/tree/?h=imx_5.4.47_2.2.0. Build a toolchain and
cross-compile the user space sources.
From the toolchain, install the folder to set up the environment:
$ ./environment-setup-aarch64-poky-linux
Build the "caam-keygen" user space application. Go to the source folder and run the following:
$ make
Build the "caam-keygen" user space application and set the location for the generated keys and blobs:
$ make KEYBLOB_LOCATION=/data/caam/keys/
If "KEYBLOB_LOCATION" is not specified, the keys and blobs are created in the default "KEYBLOB_LOCATION", which
is /data/caam/.
3.2 Usage
1. After booting the device, make sure that cryptographic transformations using Tagged Key are registered.
name : tk(cbc(aes))
driver : tk-cbc-aes-caam
module : kernel
priority : 3000
# dmsetup targets
multipath v1.13.0
crypt v1.19.0
striped v1.6.0
linear v1.4.0
error v1.5.0
crypt should be displayed among the targets. You should also make sure that you have the /dev/mapper directory and
the /dev/mapper/control device node.
3. Verify that caam-keygen application is available:
$ ./caam-keygen
CAAM keygen usage: caam-keygen [options]
Options:
create <key_name> <key_enc> <key_mode> <key_val>
<key_name> the name of the file that will contain the black key.
A file with the same name, but with .bb extension, will contain the black blob.
<key_enc> can be ecb or ccm
<key_mode> can be -s or -t.
-s generate a black key from random with the size given in the next argument
-t generate a black key from a plaintext given in the next argument
<key_val> the size or the plaintext based on the previous argument (<key_mode>)
import <blob_name> <key_name>
<blob_name> the absolute path of the file that contains the blob
<key_name> the name of the file that will contain the black key.
4. Then, you need to provide the device with its key, the secure key, which could be created either from a defined plain
key or randomly, using the ECB or CCM encryption.
An example of generating a random black key encrypted with CCM from a plaintext of 24 bytes:
The result is a Tagged Key file written to filesystem. By default, the keys and blobs are created in "KEYBLOB_LOCATION",
which is in the /data/caam/ folder.
# ls -l /data/caam/
total 8
-rw-r--r-- 1 root root 36 Oct 27 15:54 randomkey
-rw-r--r-- 1 root root 96 Oct 27 15:54 randomkey.bb
Add a key based on the previous generated black key in the key retention service using "keyctl":
# keyctl list @s
2 keys in keyring:
790250886: ----s-rv 0 0 user: invocation_id
40799481: --alsw-v 0 0 logon: logkey:
5. Create a secure volume. It could be a physical partition, in this example, make use of an image file and mount it later.
6. Using dmsetup, create a new device-mapper device named encrypted, for example, and specify mapping table. The
table can be provided on stdin or as argument.
dmsetup -v create encrypted --table "0 $(blockdev --getsz /dev/loop0) crypt capi:tk(cbc(aes))-
plain :36:logon:logkey: 0 /dev/loop0 0 1 sector_size:512"
# mkfs.ext4 /dev/mapper/encrypted
# mkdir /mnt/encrypted
At this level, everything data you write to /mnt/encrypted is encrypted on the real block device /dev/loop0.
10. Write to device.
# umount /mnt/encrypted/
13. Restart the board. After a cold reboot, a new session key is generated.
14. Import the key from blob and add it to key retention service:
16. Specify the mapping table to encrypt the volume using dmsetup.
dmsetup -v create encrypted --table "0 $(blockdev --getsz /dev/loop0) crypt capi:tk(cbc(aes))-
plain :36:logon:logkey: 0 /dev/loop0 0 1 sector_size:512"
17. Mount.
18. Read from device. Expected result is that the text should be the same as that in step 9.
# cat /mnt/encrypted/readme.txt
3.3 Performance
The dd command can be used as a simple benchmarking utility by copying data to encrypted and partition and timing the
operations. See Appendix A. Configuration for the kernel configurations that must be enabled in to create RAM disks.
1. Load the block ramdisk module, set the desired size in blocks to 64 M.
/dev/ram0 appears.
2. Create a file with size 32M with random content.
# dmsetup -v create secram --table "0 $(blockdev --getsz /dev/ram0) crypt capi:tk(cbc(aes))-
plain :36:logon:logkey: 0 /dev/ram0 0 1 sector_size:512"
4. Remove the previous files to gain some space if there is no enough disk space.
# rm encrypted.img
5. Clear cache.
6. Write to disk.
real 0m4.817s
user 0m0.065s
sys 0m0.747s
real 0m4.181s
user 0m0.043s
sys 0m0.766s
By default, DM-Crypt sends encryption or decryption requests to the crypto layer one block at a time, making each request 512
bytes long, which is a much smaller size for hardware engine. This means the CAAM cannot deliver its best performance.
DM-Crypt can take block size parameter in the form, sector_size:<bytes>, where bytes means user-specified sector size used for
encryption. The size can be in range of 512 - 4096 bytes and must be power of two. The virtual device specifies this size as minimal
IO size and logical sector size.
AES in XTS is the most convenient cipher for block-oriented storage devices and shows significant performance gain, however,
this mode is not natively supported on i.MX’s CAAM module.
4 Revision history
5 Appendix A. Configuration
If the system needs redundancy support, DM-Crypt supports such capabilities by enabling DM-Multipath. For more details, see
DM-Crypt documentation.”
For performance measurements, the following kernel options need to be enabled:
User-space interface for hash, AEAD, and symmetric key cipher algorithms.
CONFIG_CRYPTO_USER_API=y
CONFIG_CRYPTO_USER_API_HASH=y
CONFIG_CRYPTO_USER_API_AEAD=y
CONFIG_CRYPTO_USER_API_SKCIPHER=y
CONFIG_BLK_DEV_RAM=y
CONFIG_BLK_DEV_RAM_COUNT=2
CONFIG_BLK_DEV_RAM_SIZE=300000
While NXP has implemented advanced security features, all products may be subject to
unidentified vulnerabilities. Customers are responsible for the design and operation of their
applications and products to reduce the effect of these vulnerabilities on customer’s applications
and products, and NXP accepts no liability for any vulnerability that is discovered. Customers
should implement appropriate design and operating safeguards to minimize the risks associated
with their applications and products.
NXP, the NXP logo, NXP SECURE CONNECTIONS FOR A SMARTER WORLD, COOLFLUX,
EMBRACE, GREENCHIP, HITAG, I2C BUS, ICODE, JCOP, LIFE VIBES, MIFARE, MIFARE
CLASSIC, MIFARE DESFire, MIFARE PLUS, MIFARE FLEX, MANTIS, MIFARE ULTRALIGHT,
MIFARE4MOBILE, MIGLO, NTAG, ROADLINK, SMARTLX, SMARTMX, STARPLUG, TOPFET,
TRENCHMOS, UCODE, Freescale, the Freescale logo, AltiVec, C‑5, CodeTEST, CodeWarrior,
ColdFire, ColdFire+, C‑Ware, the Energy Efficient Solutions logo, Kinetis, Layerscape, MagniV,
mobileGT, PEG, PowerQUICC, Processor Expert, QorIQ, QorIQ Qonverge, Ready Play,
SafeAssure, the SafeAssure logo, StarCore, Symphony, VortiQa, Vybrid, Airfast, BeeKit,
BeeStack, CoreNet, Flexis, MXC, Platform in a Package, QUICC Engine, SMARTMOS, Tower,
TurboLink, UMEMS, EdgeScale, EdgeLock, eIQ, and Immersive3D are trademarks of NXP
B.V. All other product or service names are the property of their respective owners. AMBA,
Arm, Arm7, Arm7TDMI, Arm9, Arm11, Artisan, big.LITTLE, Cordio, CoreLink, CoreSight, Cortex,
DesignStart, DynamIQ, Jazelle, Keil, Mali, Mbed, Mbed Enabled, NEON, POP, RealView,
SecurCore, Socrates, Thumb, TrustZone, ULINK, ULINK2, ULINK-ME, ULINK-PLUS, ULINKpro,
µVision, Versatile are trademarks or registered trademarks of Arm Limited (or its subsidiaries)
in the US and/or elsewhere. The related technology may be protected by any or all of patents,
copyrights, designs and trade secrets. All rights reserved. Oracle and Java are registered
trademarks of Oracle and/or its affiliates. The Power Architecture and Power.org word marks and
the Power and Power.org logos and related marks are trademarks and service marks licensed
by Power.org.
© NXP B.V. 2021. All rights reserved.
For more information, please visit: http://www.nxp.com
For sales office addresses, please send an email to: salesaddresses@nxp.com