Metadata-Version: 2.4
Name: cvmutils
Version: 0.1.9
Summary: Tools for confidential virtual machines
Author: Vitaly Kuznetsov
Author-email: vkuznets@redhat.com
License: LGPL-2.1-or-later
Project-URL: GitLab, https://gitlab.com/vkuznets/cvmutils/
Keywords: CVM
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: setuptools; python_version < "3.13"
Dynamic: license-file

# 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:

```bash
systemd-analyze srk > public.srk
```

or

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

## Basic Usage

```bash
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,

```bash
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.

```bash
git submodule update
pytest
```

Out of tree end-to-end tests are available at [https://gitlab.com/vkuznets/cvmutils-tests-e2e](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:**

```bash
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:

```json
{
    "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`.
