coreycothrum/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). Additional systemd dependencies can by added with MENDER/LUKS_SEAL_SYSTEMD_AFTER.
• 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 = @ system boot: randomize LUKS password if weak or still set to default value
# 1 = @ system boot: do not check LUKS password
# MENDER/LUKS_BYPASS_RANDOM_KEY  = "1"

# 0 = @ system boot: reencrypt LUKS master key(s) if password is still set to default value
# 1 = @ system boot: do no reencrypt LUKS partitions
# MENDER/LUKS_BYPASS_REENCRYPT   = "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_REENCRYPT  = "1"

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

Encrypting

Encryption is not an automated part of the build process. This native script is provided as an optional post-build action.

This is only needed when provisioning a new device from the full disk image. The mender artifacts work as-is w/o this encryption step.

To execute the encryption script:

bitbake       mender-luks-encrypt-image-native -caddto_recipe_sysroot       && \
oe-run-native mender-luks-encrypt-image-native mender-luks-encrypt-image.sh <path_to_deploy_image>

This will take awhile. If it fails, it may not cleanup gracefully. Check /dev/mapper and /dev/loop* and cleanup as needed (hint(s): sudo dmsetup remove --force <NAME> and sudo losetup && sudo losetup -D).

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.

Release Schedule and Roadmap

This layer will remain compatible with the latest YOCTO LTS. This mirrors what meta-mender does.

meta-mender-luks's Issues

create update module for boot partition

requirements TBD

`acpi=off` breaks password agent

Somehow, setting the acpi kernel command-line parameter to acpi=off stops mender-luks-password-agent from working.

This is my implementation of a systemd password agent. This is needed for unattended decryption/booting (e.g. w/ a TPM module).

When acpi=off, the boot prompt doesn't pause... it immediately fails.

One wrinkle when I discovered this is I was messing around w/ stuff that would have locked the TPM during boot. So I wouldn't expect it to decrypt automatically. There should be a fallback where the system pauses for me type the password... but that doesn't happen. mender-luks-password-agent may be returning an empty string or something? It's not giving me time.

If the TPM was still good, maybe this would continue to work.... but there would be no fail-safe.

I'm not sure how/why these are related?

grub-efi: mender-luks-initramfs.packagedata WARNING

WARNING: grub-efi-2.04-r0 do_package: Manifest /yocto_workspace/build/tmp/sstate-control/manifest-x86_64_x86_64-nativesdk-mender-luks-initramfs.packagedata not found in genericx86_64 core2-64 x86_64 allarch x86_64_x86_64-nativesdk (variant '')?

idea: cryptsetup (online) reencrypt for unique LUKS master key

Current LUKS keys are defined @ build time. All devices provisioned from that build share the same LUKS master key.

Would it be good to perform a cryptsetup reencrypt? Ideally just once. This would give each device unique keys.

Probably some sort of systemd service @ boot time.

https://man7.org/linux/man-pages/man8/cryptsetup.8.html

mender-partuuid

@coreycothrum I'm using a compulab board with an imx8mp part. They have a mender configuration that uses mender-partuuid. Integrating your layer I see

ERROR: mender-luks does not currently support mender-partuuid

This is the referenced line

https://github.com/compulab-yokneam/meta-mender-compulab/blob/gatesgarth/templates/local.conf.append#L15

Do you have any thoughts on what I can do to resolve this?

initramfs: support unattended boot from network/server hosted keyfile

initramfs: support unattended boot from USB stick keyfile

invalid candidate rootfs mounted when doing multiple updates w/o reboot

only the variable mender_boot_part is used to determine the active partition. During an update that is then inverted to determine what the new root candidate partition is.

That candidate is then mounted, and the new/candidate kernel copied into the corresponding kernel partition (via meta-mender-kernel state scripts).

After an update, mender_boot_part is modified. If you do another update (before rebooting, so essentially overwriting the update with another before it takes effect), this logic is wrong. You'll copy the kernel from the active/current partition.

This logic should include upgrade_available, and not invert mender_boot_part if an update is already in process.

update to kirkstone LTS

allow booting from non-LUKs partition + online conversion/encryption

1. Support booting w/o a LUKs partition
2. Option to convert to LUKs/encrypt after first boot. Similar to the new reencrypt capability.

This would/could eliminate the need to encrypt the image before provisioning devices.

Workspace example?

Hi,
First, thanks for providing this tool. I'm trying to set it up in my workspace and encountered some little issues here and there but could hopefully create an image.
I'm testing with Yocto dunfell on qemu-X64 at the moment with the linux-yocto kernel.

I managed to build the image but I end up in the Uefi console. I tried starting grub from there but I ended up with a black screen.

This is my current configuration:

MACHINE = "qemux86-64"

# MENDER-LUKS config
MENDER/KERNEL_PART_A_NAME                  = "kernela"
MENDER/KERNEL_PART_B_NAME                  = "kernelb"

require conf/include/mender-luks.inc
require conf/include/mender-kernel.inc

IMAGE_INSTALL_append = "packagegroup-mender-luks"
MENDER/KERNEL_PART_SIZE_MB = "128"
MENDER/LUKS_PASSWORD           = "password"

# MENDER Config
MENDER_FEATURES_ENABLE_append = " mender-grub mender-image-uefi"
MENDER_FEATURES_DISABLE_append = " mender-uboot mender-image-sd"

# Yocto config
RM_OLD_IMAGE = "1"

GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_LINGUAS ?= "en-us"

NOHDD="1"
NOISO="1"

USER_CLASSES ?= "buildstats image-mklibs image-prelink"
PACKAGE_CLASSES = "package_deb"
PACKAGE_FEED_BASE_PATHS = "deb"
IMAGE_OVERHEAD_FACTOR = "1.0"
EXTRA_IMAGE_FEATURES = "ssh-server-openssh package-management debug-tweaks splash tools-debug allow-empty-password debug-tweaks post-install-logging tools-profile"

DISTRO_FEATURES_remove = "bluetooth"
DISTRO_FEATURES_remove = "3g"
DISTRO_FEATURES_remove = "nfc"
DISTRO_FEATURES_remove = "nfs"
DISTRO_FEATURES_remove = "ext2"

DISTRO_FEATURES_append = " systemd "
DISTRO_FEATURES_BACKFILL_CONSIDERED += "sysvinit"
VIRTUAL-RUNTIME_init_manager = "systemd"
VIRTUAL-RUNTIME_initscripts = "systemd-compat-units"

I used cryptsetup 2.3.2 on an ubuntu server, compiled it myself to make it work. I am not sure what I am missing but any help would be appreciated.

Edit: I tried enabling efi-secure-boot but i have the same result

Support for MENDER_EXTRA_PARTS

Allow additional MENDER_EXTRA_PARTS.

Encrypt these extra partitions.

`abort-if-update-in-progress.sh` logic incorrect

see: coreycothrum/meta-mender-kernel#7 (comment)

running mender-luks-encrypt-image.sh multiple times doesn't work

Image won't boot if you encrypt/post-process it more than once.

build/bitbake environment requires sudo

The UEFI image is encrypted after it's generated. This is done by mounting it as a loopback (via losetup and dmsetup) and using cryptsetup reencrypt. This requires access to /dev and some kernel modules. All in, it requires sudo access to the host machine.

That isn't great, and kind of goes against best practices for yocto/bitbake and/or running docker containers.

Try and determine if this is really necessary, and do it better if able.

mender-luks-cryptsetup gives Not compatible PBKDF options.

@coreycothrum to get around this I changed --type from luks1 to luks2.

I guess I can also change the pbkdf option. Not sure this is a bug but figured I'd post in case you have any thoughts.