Skip to content

README.md

Latest commit

 

History

History
201 lines (132 loc) · 6.38 KB

README.md

File metadata and controls

201 lines (132 loc) · 6.38 KB

cryptpilot-fde: Full Disk Encryption for Confidential Computing

License

cryptpilot-fde provides Full Disk Encryption (FDE) capabilities for confidential computing environments. It encrypts the entire system disk, protects boot integrity, and enables secure boot with remote attestation.

The usage workflow is shown below:

graph LR
    %% Trusted Environment
    subgraph TrustedEnv [Trusted Environment]
        User((User)) -->|1. Prepare| Trustee[Trustee Service]
        Trustee -->|2. Create| Image1[Confidential System Disk Image]
    end

    %% Cloud Service Provider Environment
    subgraph CloudEnv [Cloud Service Provider Environment]
        Image2[Confidential System Disk Image] -->|4. Create| Instance[Confidential Computing Instance]
    end

    %% Cross-region Actions
    Image1 -->|3. Import| Image2

    %% Dashed Interaction Logic
    Instance -.->|Access Trustee at boot time<br>Remote attestation and obtain decryption key| Trustee

    %% Style Adjustments
    style TrustedEnv fill:#f9f9f9,stroke:#333,stroke-width:1px
    style CloudEnv fill:#eef3ff,stroke:#333,stroke-width:1px
    style Instance fill:#fff,stroke:#0277bd,stroke-width:2px
Loading

Features

  • Full Disk Encryption: Encrypts both rootfs and data partitions
  • Integrity Protection: Uses dm-verity to protect read-only rootfs
  • Measurement & Attestation: Measures boot artifacts for remote attestation
  • Flexible Key Management: Supports KBS, KMS, OIDC, TPM2, and custom exec providers
  • Overlay Filesystem: Provides writable overlay on read-only encrypted rootfs

Installation

Install from the latest release:

# Host package: provides cryptpilot-convert, cryptpilot-enhance, and
# cryptpilot-fde-host for building encrypted disk images
rpm --install cryptpilot-fde-host-*.rpm

# Guest package: contains components that run inside the target VM at boot
# time (initrd decryption, dm-verity, LVM, overlayfs). This package is
# automatically installed into the guest rootfs by cryptpilot-convert.
rpm --install cryptpilot-fde-guest-*.rpm

Or build from source (see Development Guide).

Packages

The FDE functionality is delivered as two separate packages:

Package Purpose Key Binaries Where It Runs
cryptpilot-fde-host Disk image conversion and configuration cryptpilot-convert, cryptpilot-enhance, cryptpilot-fde-host Build environment / host machine
cryptpilot-fde-guest Guest boot-time decryption and setup cryptpilot-fde-guest, dracut module, udev rules Inside the target VM (initrd)

The host package pulls in heavy build-time dependencies (qemu-img, libguestfs) and is only used when creating encrypted images via cryptpilot-convert.

The guest package contains only the components needed at boot time and is installed into the guest rootfs during the conversion process. It should not carry the heavy host-side dependencies.

Quick Start

Encrypt a bootable disk image:

cryptpilot-convert --in ./original.qcow2 --out ./encrypted.qcow2 \
    -c ./config_dir/ --rootfs-passphrase MyPassword

📖 Detailed Quick Start Guide

Configuration

Configuration files are located in /etc/cryptpilot/:

  • fde.toml: FDE configuration (rootfs and data volumes)
  • global.toml: Global settings (optional)

See Configuration Guide for detailed options.

Configuration Templates

Commands

cryptpilot-fde-host show-reference-value

Display cryptographic reference values for attestation:

cryptpilot-fde-host show-reference-value --disk /path/to/disk.qcow2

cryptpilot-fde-host config check

Validate FDE configuration:

cryptpilot-fde-host config check --keep-checking

cryptpilot-fde-host config dump

Export configuration as TOML for cloud-init:

cryptpilot-fde-host config dump --disk /dev/sda

cryptpilot-fde-guest boot-service

Internal commands used by systemd during boot (do not call manually):

cryptpilot-fde-guest boot-service --stage before-sysroot
cryptpilot-fde-guest boot-service --stage after-sysroot

Helper Scripts

cryptpilot-convert

Convert and encrypt existing disk images or system disks:

cryptpilot-convert --help

cryptpilot-enhance

Harden VM disk images before encryption (removes cloud agents, protects SSH):

cryptpilot-enhance --mode full --image ./disk.qcow2

See cryptpilot-enhance documentation for details.

Documentation

How It Works

cryptpilot-fde runs in the initrd and operates in two stages:

  1. Before Sysroot Mount (before-sysroot stage):

    • Decrypts rootfs (if encrypted)
    • Sets up dm-verity integrity protection
    • Measures boot artifacts and generates attestation evidence
    • Decrypts and mounts data partition

  2. After Sysroot Mount (after-sysroot stage):

    • Sets up writable overlay on read-only rootfs
    • Overlay stored on encrypted data partition or tmpfs
    • Prepares system for switch_root

See Boot Process Documentation for details.

Key Providers

Multiple key providers are supported for flexible key management:

  • KBS: Key Broker Service with remote attestation
  • KMS: Alibaba Cloud Key Management Service
  • OIDC: KMS using OpenID Connect authentication
  • Exec: Custom executable that provides the key

See Key Providers for detailed configuration.

Supported Distributions

License

Apache-2.0

See Also