Skip to content

README.md

Latest commit

 

History

History
285 lines (201 loc) · 8.35 KB

README.md

File metadata and controls

285 lines (201 loc) · 8.35 KB

cryptpilot-crypt: Runtime Volume Encryption

License

cryptpilot-crypt provides runtime encryption for data volumes in confidential computing environments. It manages encrypted LUKS2 volumes with flexible key management and automatic mounting.

Features

  • Volume Encryption: Encrypt individual data volumes with LUKS2
  • Multiple Key Providers: KBS, KMS, OIDC, TPM2, Exec, OTP
  • Auto-Open: Automatically decrypt and mount volumes at boot
  • Integrity Protection: Optional dm-integrity for data authenticity
  • Flexible File Systems: Support for ext4, xfs, vfat, swap

Encryption and Integrity

cryptpilot-crypt uses the following algorithms for LUKS2 volumes:

  • Encryption: aes-xts-plain64
  • Integrity (when enabled): hmac-sha256

Kernel Configuration Requirements

The following kernel config options are always required for encryption:

CONFIG_CRYPTO_AES=y
CONFIG_CRYPTO_AES_NI_INTEL=y
CONFIG_CRYPTO_XTS=y

When integrity = true is enabled, the following additional options are required:

CONFIG_DM_INTEGRITY=y
CONFIG_DM_BUFIO=y
CONFIG_CRYPTO_HMAC=y
CONFIG_AS_SHA256_NI=y

Installation

Install from the latest release:

# Install cryptpilot-crypt package
rpm --install cryptpilot-crypt-*.rpm

Or build from source (see Development Guide).

Quick Start

Encrypt a data volume:

# Create configuration
cat > /etc/cryptpilot/volumes/data0.toml << EOF
volume = "data0"
dev = "/dev/nvme1n1p1"
auto_open = true
makefs = "ext4"

[encrypt.otp]
EOF

# Initialize and open
cryptpilot-crypt init data0
cryptpilot-crypt open data0
mount /dev/mapper/data0 /mnt/data0

📖 Detailed Quick Start Guide

Configuration

Configuration files are located in /etc/cryptpilot/volumes/:

  • Each .toml file defines one volume
  • File name can be arbitrary (e.g., data0.toml, backup.toml)

See Configuration Guide for detailed options.

Configuration Example Templates

Commands

cryptpilot-crypt show

Display status of all configured volumes:

cryptpilot-crypt show [volume-name...] [--json]

Options:

  • volume-name: Optional volume name(s) to show. If not specified, show all volumes.
  • --json: Output as JSON format instead of table

Examples:

# Show all volumes
cryptpilot-crypt show

# Show specific volume(s)
cryptpilot-crypt show data0
cryptpilot-crypt show data0 data1

# Output as JSON
cryptpilot-crypt show --json
cryptpilot-crypt show data0 --json

Example table output:

╭────────┬───────────────────┬─────────────────┬──────────────┬──────────────────┬───────────────╮
│ Volume ┆ Volume Path       ┆ Underlay Device ┆ Key Provider ┆ Extra Options    ┆ Status        │
╞════════╪═══════════════════╪═════════════════╪══════════════╪══════════════════╪═══════════════╡
│ data0  ┆ /dev/mapper/data0 ┆ /dev/nvme1n1p1  ┆ otp          ┆ auto_open = true ┆ ReadyToOpen   │
│        ┆                   ┆                 ┆              ┆ makefs = "ext4"  ┆               │
│        ┆                   ┆                 ┆              ┆ integrity = true ┆               │
╰────────┴───────────────────┴─────────────────┴──────────────┴──────────────────┴───────────────╯

Example JSON output:

[
  {
    "volume": "data0",
    "volume_path": "/dev/mapper/data0",
    "underlay_device": "/dev/nvme1n1p1",
    "key_provider": "otp",
    "extra_options": {
      "auto_open": true,
      "makefs": "ext4",
      "integrity": true
    },
    "status": "ReadyToOpen",
    "description": "Volume 'data0' uses otp key provider (temporary volume) and is ready to open"
  }
]

JSON output fields:

  • volume: Volume name
  • volume_path: Path to the decrypted volume (always shows the mapper path)
  • underlay_device: Underlying encrypted block device path
  • key_provider: Key provider type (e.g., otp, kbs, kms, oidc, exec)
  • extra_options: Additional volume configuration (null if serialization fails)
  • status: Current status of the volume (DeviceNotFound, CheckFailed, RequiresInit, ReadyToOpen, Opened)
  • description: Human-readable description of the current status

cryptpilot-crypt init

Initialize a new encrypted volume:

cryptpilot-crypt init <volume-name>

cryptpilot-crypt open

Open (decrypt) an encrypted volume:

cryptpilot-crypt open <volume-name>

Options:

  • --check-fs: Check if the filesystem is initialized after opening the volume

cryptpilot-crypt close

Close (unmount and lock) a volume:

cryptpilot-crypt close <volume-name>

cryptpilot-crypt config check

Validate volume configurations:

cryptpilot-crypt config check [--keep-checking] [--skip-check-passphrase]

Options:

  • --keep-checking: Continue checking all volumes even if errors found
  • --skip-check-passphrase: Skip passphrase validation

Volume Configuration Options

Each volume configuration supports:

  • volume (required): Volume name (used as /dev/mapper/<volume>)
  • dev (required): Underlying block device path
  • auto_open (optional, default: false): Auto-decrypt at boot
  • makefs (optional): File system type (ext4, xfs, vfat, swap)
  • integrity (optional, default: false): Enable dm-integrity
  • encrypt (required): Key provider configuration

See Configuration Guide for details.

Key Providers

Supports multiple key providers:

  • OTP: One-time password (volatile, regenerated each open)
  • KBS: Key Broker Service with remote attestation
  • KMS: Alibaba Cloud KMS with Access Key authentication
  • OIDC: KMS with OpenID Connect authentication
  • Exec: Custom executable providing keys

See Key Providers for detailed configuration.

Documentation

Use Cases

Temporary/Volatile Storage (OTP)

Use OTP provider for scratch space that's wiped on each reboot:

[encrypt.otp]

Persistent Encrypted Storage (KBS)

Use KBS for production workloads with attestation:

[encrypt.kbs]
url = "https://kbs.example.com"
resource_path = "/secrets/volume-key"

Cloud-Managed Keys (KMS)

Use Alibaba Cloud KMS for centralized key management:

[encrypt.kms]
kms_instance_id = "kst-****"
client_key_id = "LTAI****"
client_key_password_from_kms = "alias/ClientKey_****"

Integration with /etc/fstab

After opening a volume, add to /etc/fstab for automatic mounting:

echo "/dev/mapper/data0 /mnt/data0 ext4 defaults 0 2" >> /etc/fstab

Combined with auto_open = true, volumes will be decrypted and mounted automatically.

Supported Distributions

License

Apache-2.0

See Also