DStack-Util Core

Complete guide to dstack’s TDX control utility, system setup, and cryptographic services for secure computing environments

dstack-util Core Implementation: TDX Control Utility and System Setup Services

The dstack-util is a comprehensive command-line utility written in Rust that provides TDX attestation, system initialization, cryptographic services, and container management for Confidential Virtual Machines (CVMs) in the dstack system. 1

Core Architecture

The dstack-util serves as the primary interface for TDX operations and system management, integrating multiple components:

• Main CLI Interface: Handles command parsing and routing 2
• System Setup Module: Comprehensive system initialization with full disk encryption 3
• Cryptographic Services: X25519 Diffie-Hellman key agreement and AES-GCM encryption/decryption 4
• TDX Attestation: Integration with tdx-attest library for low-level TDX functionality 5

Commands Reference

Command	Purpose	Parameters
Report	Get TDX report from stdin report data	None (reads from stdin)
Quote	Generate TDX quote from stdin report data	None (reads from stdin)
Extend	Extend Runtime Measurement Register (RTMR)	—event, —payload
Show	Display current RTMR state and measurements	None
Setup	Complete system preparation with FDE	—work-dir, —device, —mount-point
GenRaCert	Generate Remote Attestation certificate	—ca-cert, —ca-key, —cert-path, —key-path
GenCaCert	Generate Certificate Authority certificate	—cert, —key, —ca-level
GenAppKeys	Generate application keys	—ca-level, —output
Hex	Hex encode data from file or stdin	filename (optional)
Rand	Generate random data	—bytes, —output, —hex
NotifyHost	Send notifications to host system	—url, —event, —payload
RemoveOrphans	Clean up orphaned Docker containers	—compose

6

Core Components

1. TDX Attestation Engine

The core TDX functionality handles essential secure computing operations:

• TDX Report Generation: Creates attestation reports from 64-byte report data 7
• TDX Quote Generation: Produces signed quotes for remote attestation 8
• RTMR Extension Operations: Extends Runtime Measurement Registers with application events 9
• Measurement Display: Shows current RTMR state and decoded measurement information 10

2. System Setup and Full Disk Encryption

The Setup command provides comprehensive system initialization including:

LUKS2 Disk Encryption Setup

• Encryption Configuration: Uses AES-XTS-Plain64 cipher with PBKDF2 key derivation 11
• ZFS Integration: Creates encrypted ZFS pools with Blake3 checksums and autoexpand capabilities 12
• Mount Management: Handles both new initialization and existing disk mounting 13

Key Management Integration

• KMS-based Key Retrieval: Supports remote key management services with attestation 14
• Local Key Provider: SGX-based key derivation for isolated environments 15
• Key Provider Verification: Validates and measures key providers for security 16

3. Cryptographic Services

Advanced cryptographic operations including:

• Certificate Generation: Creates Remote Attestation TLS certificates with TDX quotes 17
• CA Certificate Creation: Generates Certificate Authority certificates with attestation 18
• Application Key Management: Produces complete application key sets with quotes 19
• X25519 Operations: X25519 key agreement and AES-GCM decryption 4

4. Container Management

Docker integration and container lifecycle management:

• Orphaned Container Cleanup: Identifies and removes containers from outdated compose configurations 20
• Docker Registry Setup: Configures mirror registries and authentication 21
• Account Configuration: Handles Docker login with encrypted tokens 22

Usage Examples

TDX Operations

# Generate TDX quote
echo -n "report_data_64_bytes_exactly_here_padding_needed_for_full_length" | dstack-util quote

# Extend RTMR with application event
dstack-util extend --event "app-start" --payload "$(echo -n 'application_data' | hexdump -ve '1/1 "%.2x"')"

# Show current measurements
dstack-util show

System Setup with Full Disk Encryption

# Complete system setup with encrypted disk
dstack-util setup \
  --work-dir /dstack \
  --device /dev/vda2 \
  --mount-point /dstack/data

Certificate Generation

# Generate CA certificate with TDX attestation
dstack-util gen-ca-cert \
  --cert /path/to/ca.pem \
  --key /path/to/ca.key \
  --ca-level 1

# Generate application keys
dstack-util gen-app-keys \
  --ca-level 1 \
  --output /path/to/app_keys.json

Container Management

# Remove orphaned containers
dstack-util remove-orphans --compose docker-compose.yaml

# Generate random data
dstack-util rand --bytes 32 --hex

Security Features

Measurement and Attestation

The system implements comprehensive measurement logging:

• Application Composition Measurement: Hashes and extends compose file contents to RTMR 23
• Key Provider Verification: Measures and validates key provider information 24
• Boot Process Measurement: Tracks system initialization stages through RTMR extensions 25

Encryption Implementation

• LUKS2 with AES-XTS-Plain64: Industry-standard full disk encryption
• ZFS Integration: Provides data integrity with cryptographic verification
• Secure Key Derivation: Uses TDX measurements for deterministic key generation
• Multiple Key Providers: Supports KMS, local SGX, and none configurations

Integration Points

Guest Agent Integration

The system integrates with the dstack guest agent through:

• Configuration Generation: Creates agent.json with disk paths and PCCS URL 26
• Measurement Reporting: Extends RTMRs with system state information
• Secure Communication: Establishes encrypted channels for host communication

Gateway Integration

For network connectivity and secure communication:

• WireGuard VPN Setup: Configures secure tunnels with TDX-attested certificates 27
• Certificate-based Authentication: Uses Remote Attestation TLS for gateway registration 28
• Firewall Configuration: Sets up iptables rules for secure WireGuard operation 29

Host Communication

Provides secure bidirectional communication with the host system:

• Event Notification: Sends structured events and payloads to host API 30
• Progress Reporting: Updates host on system initialization stages
• Configuration Synchronization: Loads system and application configuration from host

System Lifecycle

Initialization Flow

The system initialization process proceeds through the following steps:

1. System Boot: The system starts up and begins the initialization sequence.
2. Load Host Shared Files: Shared files from the host are loaded into the environment. 31
3. Measure App Composition: The application composition (such as configuration and compose files) is measured and logged for attestation. 23
4. Request App Keys: The system requests application keys from the configured key provider. 32
5. Setup Disk Encryption: Full disk encryption is set up using the provided or derived keys. 13
6. Mount Data Disk: The encrypted data disk is mounted and made available to the system.
7. Configure Network: Network interfaces and secure tunnels (such as WireGuard) are configured. 27
8. Setup Docker: The Docker runtime is initialized and prepared for container workloads. 33
9. System Ready: The system signals readiness for operation and workloads can be started.

Key Provider Flow

The key provider flow proceeds as follows:

A. Determine Key Provider: The system first determines which key provider is configured (KMS, Local, or None). 32

B. Provider Type:

• If KMS: 34 C. Connect to the Key Management Service (KMS). D. Validate the KMS certificate. E. Decrypt application keys received from KMS.
• If Local: 15 F. Retrieve the local sealing key. G. Derive the key from SGX hardware. H. Decrypt application keys using the derived key.
• If None: 35 I. Generate temporary keys using a random generator. J. Decrypt application keys with the generated key.

K. Verify Provider ID: After obtaining the keys, the system verifies the provider’s identity. 16

L. Measure Provider: Finally, the provider’s information is measured and logged for attestation. 24

This stepwise process ensures that the correct key material is securely obtained and validated, regardless of the provider type.

Dependencies and Integration

The utility integrates with multiple dstack components:

• tdx-attest: Low-level TDX operations and RTMR management 5
• ra-tls: Remote Attestation TLS certificate generation 36
• dstack-kms-rpc: Key Management Service communication 37
• dstack-gateway-rpc: Gateway registration and WireGuard setup 38
• host-api: Host system communication and event reporting 39

Error Handling and Reliability

The utility implements comprehensive error handling:

• Graceful Degradation: Falls back to alternative KMS URLs on failure
• Validation Checks: Verifies file sizes, certificate validity, and measurement consistency
• Retry Logic: Attempts multiple gateway URLs for redundancy
• Detailed Logging: Provides structured tracing for debugging and monitoring

Next Steps

Next: OS Core →

← Previous: Guest Agent Core

Related Topics

• Security Model - Learn about TDX attestation and measurement
• Architecture - Understand TDX integration in the system
• Key Management - Deep dive into cryptographic key handling

Notes

dstack-util is a critical component of the dstack system that bridges the gap between TEE hardware capabilities and the application layer. It handles the complex setup procedures required for secure computing in trusted execution environments, including disk encryption with LUKS, network setup with WireGuard, and integration with key management services. The tool is designed to be called both during system initialization 40 and application runtime 41 to maintain security and manage the secure environment.

The utility’s modular design allows for different key provider configurations, making it suitable for various deployment scenarios from development (no key provider) to production (KMS-based) environments. Its comprehensive measurement and attestation capabilities ensure that the system state is continuously verified and recorded in the TDX measurement registers.