meta-secure-core: initial commit

Signed-off-by: Lans Zhang <jia.zhang@windriver.com>
2026-07-16 12:47:00 +00:00 · 2017-06-22 15:22:01 +08:00
commit 1b3e594449
204 changed files with 14086 additions and 0 deletions
@@ -0,0 +1,179 @@
+### Storage Encryption
+This feature provides secure storage for application data. Some applications
+need secure storage for sensitive data which must not be accessible to another
+device. For example, only an application with the right signature can update
+the data on an encrypted SD card. If you move that SD card to another device,
+the data cannot be either read or updated. One application of this capability
+is a POS application. The application keeps tax information in secure storage
+that cannot be modified by another device.
+
+This feature gives 2 types of granularity for storage encryption. Data volume
+encryption allows the user to create encryption partition with a passphrase
+typed by the end user. Root filesystem encryption enables the data encryption
+on the entire rootfs except the boot partition.
+
+Both types of storage encryption are based on device-mapper crypt target,
+which provides transparent encryption of block devices using the kernel crypto
+API. Additionally, the utility cryptsetup is used to conveniently set up disk
+encryption, aka LUKS partition, based on device-mapper crypt target.
+
+Due to the use of TPM state to seal the passphrase used to encrypt the storage,
+the encrypted storage cannot be accessed on another machine, preventing from
+the so-called offline attack.
+
+### Dependency
+This feature depends on meta-tpm2.
+
+Note:
+Even though the hardware doesn't have a TPM 2.0 device, this feature can still
+run on it, although without the guarantee of compromise detection.
+
+### Limit
+- TPM 2.0 is validated and officially supported. But TPM 1.2 device is not
+  supported by this feature.
+
+### Data Volume Encryption
+#### Use case 1: manual operation
+##### Create the LUKS partition
+```
+# cryptsetup --type luks --cipher aes-xts-plain --hash sha256 \
+      --use-random luksFormat /dev/$dev
+```
+where $dev is the device node of the partition to be encrypted.
+
+This command initializes a LUKS partition and prompts to input an initial
+passphrase used to encrypt the data. Don't disclose the passphrase used for
+product.
+
+##### Open the LUKS partition
+```
+# cryptsetup luksOpen /dev/$dev $name
+```
+This command opens the LUKS device $dev and sets up a mapping $name after
+successful verification of the supplied passphrase typed interactively. From
+now on, the data written to /dev/mapper/$name is encrypted and the data
+read back from /dev/mapper/$name is decrypted transparently and automatically.
+
+##### Create the filesystem on top of the LUKS partition
+The user can run any available filesytem formatting program on
+/dev/mapper/$name to create the filesytem with the data encryption.
+
+##### Close the LUKS partition
+```
+# cryptsetup luksClose $name
+```
+This command removes the existing mapping $name and wipes the key from kernel
+memory.
+
+To access the encryped partition, follow the instruction "Open the LUKS partition"
+and then manually mount /dev/mapper/$name to a mount point.
+
+#### Use case 2: luks-setup.sh
+This script provides a semi automatic method to set up LUKS partition. The user
+still needs to manually create the filesystem on top of the newly created LUKS
+partition.
+
+##### LUKS partition creation
+In runtime, for example, create LUKS partition on /dev/sdb1 with the
+name "my_luks_part":
+```
+# luks-setup.sh -d /dev/sdb1 -n my_luks_name -e
+```
+Note: if TPM is detected, the passphrase will be generated automatically.
+
+For more uses about luks-setup.sh, run it with -h option.
+
+##### Retrieve the passphrase
+```
+# cryptfs-tpm2 -q unseal passphrase -P sha1 -o /tmp/passphrase
+```
+This command will unseal the passphrase from TPM device and save the content
+of passphrase to the file /tmp/passphrase.
+
+The passphrase should not be disclosed and needs to be backed up to a off-line
+storage.
+
+##### Open the LUKS partition
+```
+# cryptsetup luksOpen --key-file /tmp/passphrase /dev/$dev $name
+```
+##### Mount the LUKS partition
+```
+# mount /dev/mapper/$name $mount_point
+```
+The remaining operations are left to the user. Don't forget to close the LUKS
+partition if not used.
+
+Note:
+If TPM device exists in the system, the passphrase will be bound to PCR 7,
+gating the unseal operation. If the value of PCR 7 when unsealing the
+passphrase doesn't match up the value when creating the passphrase, the
+passphrase cannot be unsealed. The value of PCR 7 is usually affected by the
+status of UEFI secure boot.
+
+### Root Filesystem Encryption
+This enables the data encryption on the rootfs without the need of a human
+entering an user passphrase. Therefore, it is required to employ an initramfs
+where the unique identity from the platform is collected from the devices on
+the platform and used to unlock the root filesystem encryption. Meanwhile, use
+TPM to protect the user passphrase for volume decryption to avoid disclosing
+the user passphrase. If the TPM device is not detected, the end user will be
+prompted to type the user passphrase.
+
+#### Operations
+Note:
+The instructions below with the prefix "[TPM]" indicate the operation
+requires TPM device. Oppositely, the prefix "[Non-TPM]" indicates this
+operation is required if the target board doesn't have a TPM device.
+
+- Ensure a hard drive is attached on target board
+  WARNNING: the following instructions will wipe all data in the hard drive.
+
+- Create overc installer on a USB device
+  Refer to layers/meta-overc/README.install for the details about how to
+  run cubeit to install overc installer to a USB device.
+
+- Attach the USB device to the board
+
+- Power on
+
+- [TPM] Clear TPM
+  Refer to meta-tpm2/README.md for the details.
+
+- Boot to Linux
+
+- Install overc runtime on the hard drive
+  Refer to layers/meta-overc/README.install for the details about how to
+  run cubeit-installer to install overc runtime to a hard drive. In
+  addition, beware of specifying "--encrypt" option to set up an
+  encrypted rootfs.
+
+- Reboot
+  After reboot to initramfs, it employs a init script to transparently
+  unseal the passphrase and mount the rootfs without any interaction.
+
+### Best Practice
+- The benefit of anchoring the TPM is that the machine status cannot be
+  compromised by any attack. If compromised, the system cannot boot up
+  due to the failure when mouting the rootfs, or access the encrypted partition
+  when mounting the LUKS partition. This is caused by the fact that the content
+  of PCR 7 is different with the value when creating the encrypted storage.
+  Usually, the content of PCR 7 is calculated based on the status of UEFI
+  secure boot.
+
+  Based on the above conclusion, it is recommended to provision UEFI secure
+  boot and turn on it prior to setting up the encrypted storage.
+
+- The non-default seal secret is supported to provide extra protection, and it
+  is user configurable. Modify the values of CRYPTFS_TPM2_PRIMARY_KEY_SECRET
+  and CRYPTFS_TPM2_PASSPHRASE_SECRET in cryptfs-tpm2 with your preference.
+
+### Known Issues
+- The default IMA rules provides the ability of measuring the boot components
+  and calculating the aggregate integrity value for attesting. However, this
+  function conflicts with this feature which employs PCR policy session to
+  retrieve the passphrase in a safe way. If the installer enables both of
+  them, the default IMA rules will be not used.
+
+### Reference
+- [OpenEmbedded layer for TPM 2.0 enablement](https://github.com/jiazhang0/meta-tpm2)
@@ -0,0 +1,15 @@
+# We have a conf and classes directory, add to BBPATH
+BBPATH .= ":${LAYERDIR}"
+
+# We have recipes-* directories, add to BBFILES
+BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+	${LAYERDIR}/recipes-*/*/*.bbappend"
+
+BBFILE_COLLECTIONS += "encrypted-storage"
+BBFILE_PATTERN_encrypted-storage = "^${LAYERDIR}/"
+BBFILE_PRIORITY_encrypted-storage = "10"
+
+LAYERDEPENDS_encrypted-storage = "\
+    core \
+    tpm2 \
+"
@@ -0,0 +1,8 @@
+include packagegroup-encrypted-storage.inc
+
+DESCRIPTION = "The packages used for encrypted storage in initramfs."
+
+RDEPENDS_${PN} += " \
+    cryptfs-tpm2-initramfs \
+    packagegroup-tpm2-initramfs \
+"
@@ -0,0 +1,14 @@
+include packagegroup-encrypted-storage.inc
+
+DESCRIPTION = "The packages used for encrypted storage."
+
+# Install the minimal stuffs only for the linux rootfs.
+# The common packages shared between initramfs and rootfs
+# are listed in the .inc.
+# @util-linux: fdisk
+# @parted: parted
+RDEPENDS_${PN} += " \
+    util-linux-fdisk \
+    parted \
+    packagegroup-tpm2 \
+"
@@ -0,0 +1,25 @@
+LICENSE = "MIT"
+LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
+                    file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+
+ALLOW_EMPTY_${PN} = "1"
+
+S = "${WORKDIR}"
+
+# Install the minimal stuffs for the common uses between initramfs
+# and linux rootfs.
+# @util-linux: mount, umount
+# @cryptsetup: cryptsetup
+# @cryptfs-tpm: tpm_gen_dmcrypt_key, tpm_unwrap_dmcrypt_key 
+# @kmod: modprobe
+# @coreutils: cat, mkdir, mknod, cp, rm
+# @trousers: tcsd
+RDEPENDS_${PN} = " \
+    util-linux-mount \
+    util-linux-umount \
+    cryptsetup \
+    kmod \
+    coreutils \
+    cryptfs-tpm2 \
+    procps \
+"
@@ -0,0 +1,6 @@
+FILESEXTRAPATHS_prepend := "${THISDIR}/linux-yocto:"
+
+SRC_URI += " \
+    ${@bb.utils.contains('DISTRO_FEATURES', 'encrypted-storage', \
+                         'file://dmcrypt.scc file://dmcrypt.cfg', '', d)} \
+"
@@ -0,0 +1 @@
+include linux-yocto-encrypted-storage.inc
@@ -0,0 +1,11 @@
+# Enable device-mapper crypt target
+CONFIG_DM_CRYPT=y
+
+# Enable the default cipher-spec for LUKS
+CONFIG_CRYPTO_AES=y
+CONFIG_CRYPTO_AES_NI_INTEL=y
+CONFIG_CRYPTO_XTS=y
+
+# Use entropy-strong source for RNG
+CONFIG_HW_RANDOM=y
+CONFIG_HW_RANDOM_TPM=m
@@ -0,0 +1 @@
+kconf non-hardware dmcrypt.cfg
@@ -0,0 +1 @@
+include linux-yocto-encrypted-storage.inc
@@ -0,0 +1,55 @@
+SUMMARY = "A tool used to create, persist, evict a passphrase \
+for full-disk-encryption with TPM 2.0"
+DESCRIPTION = " \
+This project provides with an implementation for \
+creating, persisting and evicting a passphrase with TPM 2.0. \
+The passphrase and its associated primary key are automatically \
+created by RNG engine in TPM. In order to avoid saving the \
+context file, the created passphrase and primary key are always \
+persistent in TPM. \
+"
+SECTION = "devel"
+LICENSE = "BSD-3-Clause"
+LIC_FILES_CHKSUM = "file://${S}/LICENSE;md5=89c8ce1346a3dfe75379e84f3ba9d641"
+
+SRC_URI = " \
+    git://github.com/WindRiver-OpenSourceLabs/cryptfs-tpm2.git \
+"
+SRCREV = "32b49092d54b3d59c482d77d5eb1e36993912e89"
+PV = "0.6.0+git${SRCPV}"
+
+DEPENDS += "tpm2.0-tss tpm2-abrmd pkgconfig-native"
+RDEPENDS_${PN} += "libtss2 libtctidevice libtctisocket"
+
+PACKAGES =+ " \
+    ${PN}-initramfs \
+"
+
+PARALLEL_MAKE = ""
+
+S = "${WORKDIR}/git"
+
+EXTRA_OEMAKE = " \
+    sbindir="${sbindir}" \
+    libdir="${libdir}" \
+    includedir="${includedir}" \
+    tpm2_tss_includedir="${STAGING_INCDIR}/sapi" \
+    tpm2_tss_libdir="${STAGING_LIBDIR}" \
+    tpm2_tabrmd_includedir="${STAGING_INCDIR}" \
+    CC="${CC}" \
+    PKG_CONFIG="${STAGING_BINDIR_NATIVE}/pkg-config" \
+    EXTRA_CFLAGS="${CFLAGS}" \
+    EXTRA_LDFLAGS="${LDFLAGS}" \
+"
+
+do_install() {
+    oe_runmake install DESTDIR="${D}"
+
+    if [ x"${@bb.utils.contains('DISTRO_FEATURES', 'encrypted-storage', '1', '0', d)}" = x"1" ]; then
+        install -m 0500 ${S}/script/init.cryptfs ${D}
+    fi
+}
+
+FILES_${PN}-initramfs = "\
+    /init.cryptfs \
+"