From 1b3e5944491c315ca99b832bc3afdb6a19d81430 Mon Sep 17 00:00:00 2001 From: Lans Zhang Date: Thu, 22 Jun 2017 15:22:01 +0800 Subject: meta-secure-core: initial commit Signed-off-by: Lans Zhang --- meta-encrypted-storage/README.md | 179 +++++++++++++++++++++ meta-encrypted-storage/conf/layer.conf | 15 ++ .../packagegroup-encrypted-storage-initramfs.bb | 8 + .../packagegroup-encrypted-storage.bb | 14 ++ .../packagegroup-encrypted-storage.inc | 25 +++ .../linux/linux-yocto-encrypted-storage.inc | 6 + .../recipes-kernel/linux/linux-yocto-rt_%.bbappend | 1 + .../recipes-kernel/linux/linux-yocto/dmcrypt.cfg | 11 ++ .../recipes-kernel/linux/linux-yocto/dmcrypt.scc | 1 + .../recipes-kernel/linux/linux-yocto_%.bbappend | 1 + .../recipes-tpm/cryptfs-tpm2/cryptfs-tpm2_git.bb | 55 +++++++ 11 files changed, 316 insertions(+) create mode 100644 meta-encrypted-storage/README.md create mode 100644 meta-encrypted-storage/conf/layer.conf create mode 100644 meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage-initramfs.bb create mode 100644 meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.bb create mode 100644 meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.inc create mode 100644 meta-encrypted-storage/recipes-kernel/linux/linux-yocto-encrypted-storage.inc create mode 100644 meta-encrypted-storage/recipes-kernel/linux/linux-yocto-rt_%.bbappend create mode 100644 meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.cfg create mode 100644 meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.scc create mode 100644 meta-encrypted-storage/recipes-kernel/linux/linux-yocto_%.bbappend create mode 100644 meta-encrypted-storage/recipes-tpm/cryptfs-tpm2/cryptfs-tpm2_git.bb (limited to 'meta-encrypted-storage') diff --git a/meta-encrypted-storage/README.md b/meta-encrypted-storage/README.md new file mode 100644 index 0000000..989c8be --- /dev/null +++ b/meta-encrypted-storage/README.md @@ -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) diff --git a/meta-encrypted-storage/conf/layer.conf b/meta-encrypted-storage/conf/layer.conf new file mode 100644 index 0000000..b24954c --- /dev/null +++ b/meta-encrypted-storage/conf/layer.conf @@ -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 \ +" diff --git a/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage-initramfs.bb b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage-initramfs.bb new file mode 100644 index 0000000..88e8f7f --- /dev/null +++ b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage-initramfs.bb @@ -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 \ +" diff --git a/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.bb b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.bb new file mode 100644 index 0000000..225eb6a --- /dev/null +++ b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.bb @@ -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 \ +" diff --git a/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.inc b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.inc new file mode 100644 index 0000000..ab4b778 --- /dev/null +++ b/meta-encrypted-storage/recipes-base/packagegroups/packagegroup-encrypted-storage.inc @@ -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 \ +" diff --git a/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-encrypted-storage.inc b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-encrypted-storage.inc new file mode 100644 index 0000000..198c972 --- /dev/null +++ b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-encrypted-storage.inc @@ -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)} \ +" diff --git a/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-rt_%.bbappend b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-rt_%.bbappend new file mode 100644 index 0000000..fc85431 --- /dev/null +++ b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto-rt_%.bbappend @@ -0,0 +1 @@ +include linux-yocto-encrypted-storage.inc diff --git a/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.cfg b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.cfg new file mode 100644 index 0000000..cedfcea --- /dev/null +++ b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.cfg @@ -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 diff --git a/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.scc b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.scc new file mode 100644 index 0000000..c549edd --- /dev/null +++ b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto/dmcrypt.scc @@ -0,0 +1 @@ +kconf non-hardware dmcrypt.cfg diff --git a/meta-encrypted-storage/recipes-kernel/linux/linux-yocto_%.bbappend b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto_%.bbappend new file mode 100644 index 0000000..fc85431 --- /dev/null +++ b/meta-encrypted-storage/recipes-kernel/linux/linux-yocto_%.bbappend @@ -0,0 +1 @@ +include linux-yocto-encrypted-storage.inc diff --git a/meta-encrypted-storage/recipes-tpm/cryptfs-tpm2/cryptfs-tpm2_git.bb b/meta-encrypted-storage/recipes-tpm/cryptfs-tpm2/cryptfs-tpm2_git.bb new file mode 100644 index 0000000..2ad7ed1 --- /dev/null +++ b/meta-encrypted-storage/recipes-tpm/cryptfs-tpm2/cryptfs-tpm2_git.bb @@ -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 \ +" -- cgit v1.2.3-54-g00ecf