hzappen / meta-mender-luks

mender with LUKS encrypted partitions

meta-mender-luks

LUKS encrypted rootfs and /data partitions for meta-mender. TPM2 integration for unattended boot.

Requires meta-mender-kernel for separate A/B kernel partitions.

Overview

• The /boot and A/B kernel partitions are left unencrypted.
• The rootfs and /data partitions are encrypted with detached LUKS headers. The detached headers are stored on the /boot partition.
• The LUKS passphrase is stored in plain text on the (encrypted) /data partition.
• An ArtifactInstall state-script mounts the rootfs LUKS partition for mender-client access during an update.
• Optional TPM2 integration for unattended boot.

#FIXME - flesh this out more, bootflow, etc

#FIXME - coming soon

TPM2 Integration

Requires meta-secure-core. See this kas file for more setup details.

For unattended boot, the LUKS passphrase is loaded/sealed on the TPM2 device. This should be transparent to the user.

• mender-luks-password-agent reads key and provides to cryptsetup at boot
• mender-luks-tpm-key-watcher.service updates TPM2 when/if the LUKS key changes (on the filesystem)
• mender-luks-tpm-seal-on-boot.service reseals to MENDER/LUKS_TPM_PCR_SET_MAX if no systemd services have failed after MENDER/LUKS_SEAL_DELAY_SECS (i.e. a successful boot)
• mender-luks-state-scripts-tpm reseals to MENDER/LUKS_TPM_PCR_SET_MIN after a mender artifact is written

Utilities and Services

luks-util

#FIXME - coming soon

tpm2-util

#FIXME - coming soon

Dependencies

This layer depends on:

URI: git://git.openembedded.org/bitbake

URI: git://git.openembedded.org/openembedded-core
layers: meta
branch: master

URI: https://github.com/mendersoftware/meta-mender.git
layers: meta-mender-core
branch: master

URI: https://github.com/coreycothrum/meta-mender-kernel.git
layers: meta-mender-kernel
branch: master

URI: https://github.com/coreycothrum/meta-bitbake-variable-substitution.git
layers: meta-bitbake-variable-substitution
branch: master

Installation

Add Layer to Build

In order to use this layer, the build system must be aware of it.

Assuming this layer exists at the top-level of the yocto build tree; add the location of this layer to bblayers.conf, along with any additional layers needed:

BBLAYERS ?= "                                       \
  /path/to/yocto/meta                               \
  /path/to/yocto/meta-poky                          \
  /path/to/yocto/meta-yocto-bsp                     \
  /path/to/yocto/meta-mender/meta-mender-core       \
  /path/to/yocto/meta-bitbake-variable-substitution \
  /path/to/yocto/meta-mender-kernel                 \
  /path/to/yocto/meta-mender-luks                   \
  "

Alternatively, run bitbake-layers to add:

$ bitbake-layers add-layer /path/to/yocto/meta-mender-luks

Configure Layer

The following definitions should be added to local.conf or custom_machine.conf

require conf/include/mender-luks.inc

MENDER/LUKS_PASSWORD           = "n3w_p@ssw0rd"

# 0 = encrypt IMAGE_FSTYPE @ build time
# 1 = do not encrypt IMAGE_FSTYPE. MUCH faster to build, but not suitable
#     for generating an image to provision disk with
# MENDER/LUKS_BYPASS_ENCRYPTION  = "1"

# 0 = @ boot: randomize LUKS password if weak or still set to default value
# 1 = @ boot: do not check LUKS password
# MENDER/LUKS_BYPASS_RANDOM_KEY  = "1"

# PCRs levels to seal TPM2
# MENDER/LUKS_TPM_PCR_SET_NONE   = "0"
# MENDER/LUKS_TPM_PCR_SET_MIN    = "0,1"
# MENDER/LUKS_TPM_PCR_SET_MAX    = "0,1,2,3,4,5"

kas

Alternatively, a kas file has been provided to help with setup/config. Include kas/kas.yml from this layer in the top level kas file. E.g.:

header:
  version : 1
  includes:
    - repo: meta-mender-luks
      file: kas/kas.yml

local_conf_header:
  01_meta-mender-luks: |
    # define here, or in a custom layer
    MENDER/LUKS_PASSWORD           = "n3w_p@ssw0rd"
    MENDER/LUKS_BYPASS_RANDOM_KEY  = "1"
    MENDER/LUKS_BYPASS_ENCRYPTION  = "0"

Additional files in kas/ have been provided to selectively turn on some features, such as TPM2 integration.

Building

A standalone reference build kas file has been provided.

Docker

All testing has been done with the Dockerfile located in this repo.

Example/Reference Build

Commands executed from docker image:

# clone repo
cd $YOCTO_WORKDIR && git clone https://github.com/coreycothrum/meta-mender-luks.git

# build TARGET image
cd $YOCTO_WORKDIR && kas build $YOCTO_WORKDIR/meta-mender-luks/kas/reference_builds/kas.min.x86-64.yml

# build QEMU image
cd $YOCTO_WORKDIR && kas build $YOCTO_WORKDIR/meta-mender-luks/kas/reference_builds/kas.min.x86-64.yml:$YOCTO_WORKDIR/meta-mender-luks/kas/reference_builds/kas.qemu.yml

Use Notes

• The mender update artifact (*.mender) is UNENCRYPTED.
• MENDER_BOOT_PART_SIZE_MB needs to have capacity for detached LUKS headers.
• Enabling efi-secure-boot is recommended, especially when using unattended boot (requires meta-secure-core).

Contributing

Please submit any patches against this layer via pull request.

Commits must be signed off.

Use conventional commits.