cvmutils 0.1.9

Tools for confidential virtual machines

Prepare OS Image for Confidential Environments

Purpose

These tools can be used to prepare Linux OS images to run in confidential environments. The most common use-case is pre-encrypting the root volume and sealing the key to the target vTPM. Previously, the tool was named encrypt-rhel-image and was targeted at Fedora/RHEL OS images, but support for various other distributions has been added since.

Image Prerequisites

• Partition Table: GUID Partition Table (GPT).
• ESP Partition: Image must contain an ESP partition with GUID C12A7328-F81F-11D2-BA4B-00A0C93EC93B.
• Root Partition: Image must contain a "Linux root (x86-64)" partition with GUID 4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709.
• LUKS Conversion: The root partition must be convertible to LUKS. To accommodate the LUKS header, the tool supports:
  • Resizing the root partition (requires available space after root).
  • Shrinking an ext4 filesystem.
• PCR7: The expected value can be specified explicitly (--pcr7 <sha256value>) or predicted (--pcr7 auto) using one of the following profiles:
  • UEFI profile (--uefi-profile)
  • Azure Disk Profile (--az-disk-profile)
  • EFI vars profile (--efivars-profile)

  Examples are present in test/test-data.

• PCR4: Can optionally be included in the set of PCRs for root volume key sealing. Its value can be specified directly (--pcr4 <sha256value>) or predicted (--pcr4 auto).

TPM2

SRK public key is required for the 'deploy' phase. It can be obtained with:

systemd-analyze srk > public.srk

or

tpm2_readpublic -c 0x81000001 -o public.srk -t primary.handle

Basic Usage

cvm-encrypt-image encrypt /path/to/image.vhd
cvm-encrypt-image deploy \
    -s /path/to/public.srk \
    --pcr7 auto \
    --uefi-profile uefi_profile.json \
    /path/to/image.vhd

Running in a Container

The tool can run in a container; Containerfile.fedora, Containerfile.c10s, and Containerfile.ubi10 are provided as examples to build it. Assuming all data is stored in '/data' on the host,

docker build -f Containerfile.fedora -t cvmutils-fedora .
modprobe nbd max_part=8
qemu-nbd -c /dev/nbd0 vol.raw
docker run -it --privileged --mount type=bind,source=/data,target=/data --mount type=bind,source=/run/udev,target=/run/udev --mount type=bind,source=/dev,target=/dev cvmutils-fedora:latest cvm-encrypt-image encrypt -v /dev/nbd0
docker run -it --privileged --mount type=bind,source=/data,target=/data --mount type=bind,source=/run/udev,target=/run/udev --mount type=bind,source=/dev,target=/dev cvmutils-fedora:latest cvm-encrypt-image deploy -s /data/public.srk --pcr7 auto --uefi-profile /data/uefi-profile.json -v /dev/nbd0
qemu-nbd --disconnect /dev/nbd0

Note, UBI10 does not currently provide e2fsprogs package and thus cannot be used for the encrypt phase.

Testing

The tool comes with unit tests which can be executed with pytest. Note that the test-data submodule must be checked out.

git submodule update
pytest

Out of tree end-to-end tests are available at https://gitlab.com/vkuznets/cvmutils-tests-e2e.

Dependencies

Basic:

• python3.x

'Encrypt' phase:

• qemu-nbd
• e2fsprogs
• cryptsetup
• util-linux (blkid, sfdisk)

'Deploy' phase additionally requires:

• openssl
• systemd-cryptenroll >= 255

Experimental Features

Instead of encrypting the root volume and sealing the key to the target vTPM, the tool can be used to create immutable, integrity-protected images.

Basic usage:

cvm-encrypt-image makeverity \
    --secureboot-key=custom_db.key \
    --secureboot-cert=custom_db.pem \
    --volatile-overlay vol.raw

The --secureboot-cert and --secureboot-key options are mandatory and are required to sign the expected root dm-verity hash. It is passed to the guest kernel as /loader/addons/roothash.addon.efi UKI addon on the ESP. Note that for this mode of operation, veritysetup and ukify tools must be available.

Unused Features Queued for Deprecation

ESP may contain an efivars.json file in Azure format:

{
    "type": "Microsoft.Compute/disks",
    "properties": {
        "uefiSettings": {
            "Boot0004": {
                "guid": "Yd/ki8qT0hGqDQDgmAMrjA==",
                "attributes": "Bw==",
                "value": "AQAAAGIAUwBoAGkAbQAgAGIAbwBvAHQAIAB0AG8AIAA1AC4AMQA0AC4AMAAtADIAMwA4AF8AdQBrAGkAXwB0AGUAcwB0ADEAOQAuAGUAbAA5AC4AeAA4ADYAXwA2ADQAAAAEASoAAgAAAAAoAAAAAAAAAOAHAAAAAABibF3EAi9J4o1TPhDbQRiuAgIEBDQAXABFAEYASQBcAHIAZQBkAGgAYQB0AFwAcwBoAGkAbQB4ADYANAAuAGUAZgBpAAAAf/8EAFwARQBGAEkAXABMAGkAbgB1AHgAXAB2AG0AbABpAG4AdQB6AC0ANQAuADEANAAuADAALQAyADMAOABfAHUAawBpAF8AdABlAHMAdAAxADkALgBlAGwAOQAuAHgAOAA2AF8ANgA0AC0AdgBpAHIAdAAuAGUAZgBpAAAA"
            }
        }
    }
}

In case it does, its size and content will be written to a special 'Linux reserved' GUID 8DA63339-0007-60C0-C436-083AC8230908 partition starting at offset 2048 * 512 = 1048576.