diff --git a/.gitignore b/.gitignore index 0149d458..efe9ea4d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,6 @@ generated/ node_modules/ /.cargo .venv +# macOS system files +.DS_Store +**/.DS_Store diff --git a/.mintlifyignore b/.mintlifyignore new file mode 100644 index 00000000..1b1b87e3 --- /dev/null +++ b/.mintlifyignore @@ -0,0 +1,55 @@ +# Ignore all markdown files except those in docs +*.md +!docs/**/*.md +!docs/**/*.mdx + +# Ignore all non-docs directories +basefiles/ +cc-eventlog/ +cert-client/ +certbot/ +ct_monitor/ +dstack-types/ +dstack-util/ +gateway/ +guest-agent/ +guest-api/ +host-api/ +http-client/ +iohash/ +key-provider-build/ +key-provider-client/ +kms/ +load_config/ +lspci/ +mod-tdx-guest/ +python/ +ra-rpc/ +ra-tls/ +rocket-vsock-listener/ +sdk/ +serde-duration/ +sodiumbox/ +supervisor/ +tdx-attest/ +tdx-attest-sys/ +test-scripts/ +vmm/ + +# Ignore build and config files +*.toml +*.yaml +*.yml +*.lock +*.sh +Makefile +Cargo.toml +Cargo.lock + +# Ignore hidden files +.git/ +.github/ +.* + +# Node modules +node_modules/ \ No newline at end of file diff --git a/README.md b/README.md index 4cd64e94..4c5d5835 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ In the tutorial above, we used a TLS certificate with a private key external to By combining Certificate Transparency Logs and CAA DNS records, we can make best effort to minimize security risks. Here's our approach: - Set CAA records to allow only the account created in dstack-gateway CVM to request Certificates. -- Launch a program to monitor Certificate Transparency Log and give alarm once any certificate issued to a pubkey that isn’t generated by dstack-gateway CVM. +- Launch a program to monitor Certificate Transparency Log and give alarm once any certificate issued to a pubkey that isn't generated by dstack-gateway CVM. ### Configurations @@ -322,7 +322,7 @@ $ ./ct_monitor -t https://localhost:9010/prpc -d app.kvin.wang # Troubleshooting -### Error from dstack-vmm: qemu-system-x86_64: -device vhost-vsock-pci,guest-cid=: vhost-vsock: unable to set guest cid: Address already in use +### Error from dstack-vmm: qemu-system-x86_64: -device vhost-vsock-pci,guest-cid=\: vhost-vsock: unable to set guest cid: Address already in use `dstack-vmm` may throw this error when creating a new VM if the [Unix Socket CID](https://man7.org/linux/man-pages/man7/vsock.7.html) is occupied. To solve the problem, first, you should list the occupied CID: diff --git a/docs.json b/docs.json new file mode 100644 index 00000000..821a74d9 --- /dev/null +++ b/docs.json @@ -0,0 +1,407 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "dstack", + "colors": { + "primary": "#0069ED", + "light": "#4D9CFF", + "dark": "#0050B4" + }, + "favicon": "/docs/public/favicon.png", + "navigation": { + "dropdowns": [ + { + "dropdown": "Overview", + "pages": [ + { + "group": "Welcome to DStack", + "icon": { + "name": "party-horn", + "style": "solid" + }, + "pages": [ + "docs/index" + ] + }, + { + "group": "Introduction to DStack", + "icon": { + "name": "hand-wave", + "style": "regular" + }, + "pages": [ + "docs/overview/introduction", + "docs/overview/what-is-dstack" + ] + }, + { + "group": "Additional Reading", + "icon": { + "name": "head-side-gear", + "style": "regular" + }, + "pages": [ + "docs/overview/key-features", + "docs/overview/benefits", + "docs/overview/glossary" + ] + } + ] + }, + { + "dropdown": "Getting Started", + "icon": { + "name": "stars", + "style": "solid" + }, + "pages": [ + "docs/getting-started/start", + { + "group": "Application Deployment Guide ", + "icon": { + "name": "rocket-launch", + "style": "solid" + }, + "pages": [ + "docs/getting-started/install/app-jupiter-guide" + ] + }, + { + "group": "DStack Framework Installation", + "icon": { + "name": "download", + "style": "solid" + }, + "pages": [ + "docs/getting-started/install/installation", + { + "group": "Steps", + "icon": { + "name": "shoe-prints", + "style": "duotone" + }, + "pages": [ + "docs/getting-started/install/step-1-prerequisites", + "docs/getting-started/install/step-2-update-server", + "docs/getting-started/install/step-3-install-required-packages", + "docs/getting-started/install/step-4-install-dstack-runtime" + ] + } + ] + }, + { + "group": "Cloud Deployment Preparation Manual", + "icon": { + "name": "cloud-bolt", + "style": "solid" + }, + "pages": [ + "docs/getting-started/first-deployment-steps/first-deployment", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-of-dstack-advanced", + { + "group": "Advanced Deployment Steps", + "icon": { + "name": "shoe-prints", + "style": "duotone" + }, + "pages": [ + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-1", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-2", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-3", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-4", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-5", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-6", + "docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-7" + ] + }, + + { + "group": "dstack deployment for dummies", + "icon": { + "name": "shoe-prints", + "style": "duotone" + }, + "pages": [ + "docs/getting-started/first-deployment-steps/fd-1", + "docs/getting-started/first-deployment-steps/fd-2", + "docs/getting-started/first-deployment-steps/fd-3", + "docs/getting-started/first-deployment-steps/fd-5", + "docs/getting-started/first-deployment-steps/fd-6", + "docs/getting-started/first-deployment-steps/fd-7" + ] + } + ] + }, + { + "group": "Examples", + "icon": { + "name": "circle-stop", + "style": "regular" + }, + "pages": [ + "/docs/tutorials/super-quick-start" + ] + } + ] + }, + { + "dropdown": "Core Concepts", + "icon": { + "name": "comet", + "style": "solid" + }, + "pages": [ + { + "group": "Diving Deep", + "icon": { + "name": "star-sharp", + "style": "solid" + }, + "pages": [ + "docs/concepts/overview", + "/docs/concepts/core-glossary" + ] + }, + { + "group": "KSM, VMM & Gateway", + "icon": { + "name": "code", + "style": "solid" + }, + "pages": [ + "docs/concepts/basic-components", + { + "group": "Core Implementations", + "icon": { + "name": "list-ol", + "style": "solid" + }, + "pages": [ + + "docs/concepts/core-vmm", + "docs/concepts/core-gateway", + "docs/concepts/core-kms", + "docs/concepts/core-guest-agent", + "docs/concepts/core-tdxctl", + "docs/concepts/core-os" + ] + } + + ] + }, + + { + "group": "DStack Component Architecture", + "icon": { + "name": "sitemap", + "style": "thin" + }, + "pages": [ + "docs/concepts/architecture", + "docs/concepts/networking" + ] + } + ] + }, + { + "dropdown": "Security + Research", + "icon": { + "name": "shield-plus", + "style": "solid" + }, + "pages": [ + "docs/security-research/overview", + { + "group": "DStack crypto", + "icon": { + "name": "key", + "style": "solid" + }, + "pages": [ + "docs/security-research/security-model" + ] + }, + { + "group": "Key Component Infrastructure", + "icon": { + "name": "dice-four", + "style": "solid" + }, + "pages": [ + { + "group": "tdx", + "pages": [ + "docs/security-research/tdx-att/tdx-overview", + "docs/security-research/tdx-att/tdx-security-arch", + "docs/security-research/tdx-att/tdx-quote-gen", + "docs/security-research/tdx-att/tdx-verification-model", + "docs/security-research/tdx-att/tdx-integration-review", + "docs/security-research/tdx-att/tdx-threat-model-garentees", + "docs/security-research/tdx-att/tdx-implementation" + ] + }, + { + "group": "vmm", + "pages": [ + "docs/security-research/vmm/vmm-overview", + "docs/security-research/vmm/vmm-tdx-attestation-and-measurement", + "docs/security-research/vmm/vmm-key-management", + "docs/security-research/vmm/vmm-implementation", + "docs/security-research/vmm/vmm-attestation-and-verification", + "docs/security-research/vmm/vmm-dos-protection", + "docs/security-research/vmm/vmm-procedures", + "docs/security-research/vmm/vmm-integration-arch" + ] + }, + { + "group": "gateway", + "pages": [ + "docs/security-research/gate/gate-overview", + "docs/security-research/gate/gate-cvm-registration", + "docs/security-research/gate/gate-state-sync", + "docs/security-research/gate/gate-implementation", + "docs/security-research/gate/gate-attestation-verification", + "docs/security-research/gate/gate-load-balancing", + "docs/security-research/gate/gate-notes" + ] + }, + { + "group": "kms", + "pages": [ + "docs/security-research/kms/kms-overview", + "docs/security-research/kms/kms-cert-manager", + "docs/security-research/kms/kms-implementation", + "docs/security-research/kms/kms-audit-procedures", + "docs/security-research/kms/kms-blockchain-integration", + "docs/security-research/kms/kms-security-arch", + "docs/security-research/kms/kms-security-props", + "docs/security-research/kms/kms-security" + ] + } + ] + }, + { + "group": "Additional Reading", + "icon": { + "name": "book-open", + "style": "solid" + }, + "pages": [ + "docs/security-research/extra-sec-ops/before-reading", + { + "group": "extra-sec-ops", + "pages": [ + "docs/security-research/extra-sec-ops/certbot-security", + "docs/security-research/extra-sec-ops/cert-client-security", + "docs/security-research/extra-sec-ops/ct-monitor-security", + "docs/security-research/extra-sec-ops/iohash-security", + "docs/security-research/extra-sec-ops/host-api-security" + ] + } + ] + } + ] + }, + { + "dropdown": "Tutorials", + "icon": { + "name": "apple-whole", + "style": "solid" + }, + "pages": [ + "docs/tutorials/index-quick-start", + { + "group": "Additional Starter Guides", + "icon": { + "name": "book", + "style": "regular" + }, + "pages": [ + "/docs/tutorials/javascript-example", + "/docs/tutorials/python-example", + "/docs/tutorials/rust-example" + ] + } + ] + }, + { + "dropdown": "Community & Support", + "icon": "users", + "pages": [ + "docs/community-section/community", + "docs/community-section/contribution" + ] + } + ] + }, + "logo": { + "light": "/docs/public/logo/light.png", + "dark": "/docs/public/logo/dark.png" + }, + "api": { + "mdx": { + "server": "https://api.dstack.dev", + "auth": { + "method": "bearer" + } + } + }, + "background": { + "image": "/docs/public/background.png" + }, + "navbar": { + "links": [ + { + "label": "Hosted by Phala - GitHub", + "href": "https://github.com/Dstack-TEE/dstack" + } + ], + "primary": { + "type": "button", + "label": "Publications", + "href": "https://collective.flashbots.net/t/dstack-speedrunning-a-p2p-confidential-vm/3876" + } + }, + "footer": { + "socials": { + "github": "https://github.com/Dstack-TEE/dstack", + "twitter": "https://twitter.com/PhalaNetwork", + "discord": "https://discord.gg/phala" + }, + "links": [ + { + "items": [ + { + "label": "📕 Authors Note -- TEE Guide", + "href": "https://www.intothebytecode.com/46-andrew-miller/" + } + ] + }, + { + "items": [ + { + "label": "Eliza AI Deploys on the dStack 🤯", + "href": "https://www.youtube.com/watch?v=QkGLilgQ2Yc" + }, + { + "label": "DStack Worker Agents using TEE 🤯", + "href": "https://www.youtube.com/watch?v=MCUWLUZuqJc" + } + ] + }, + { + "items": [ + { + "label": "📺 Phala dStack MCP agent video guide", + "href": "https://www.youtube.com/watch?v=qG-9f66z-G8" + } + ] + } + ] + }, + "integrations": { + "ga4": { + "measurementId": "G-XXXXXXXXXX" + } + } +} \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/glossary.mdx b/docs/api-reference/api-sub-docs/glossary.mdx new file mode 100644 index 00000000..d194617d --- /dev/null +++ b/docs/api-reference/api-sub-docs/glossary.mdx @@ -0,0 +1,23 @@ +--- +title: "API Glossary" +description: "Glossary of dstack API components and terminology." +--- + +[← Back to API Reference Overview](./overview) + +# API Glossary + +- **dstack-vmm**: Virtual Machine Manager, runs on the TDX host to manage Confidential Virtual Machines (CVMs). +- **dstack-gateway**: Reverse proxy for forwarding TLS connections to CVMs. +- **dstack-kms**: Key Management Service for generating and distributing keys to CVMs. +- **dstack-guest-agent**: Runs inside each CVM, provides cryptographic, attestation, and key management APIs. +- **supervisor**: Process management service within CVMs. +- **CVM (Confidential Virtual Machine)**: Isolated VM with hardware-backed security (Intel TDX). +- **TDX (Trust Domain Extensions)**: Intel technology for confidential computing and secure enclaves. +- **RA-TLS**: Remote Attestation TLS, cryptographic protocol for attesting enclave state. +- **App Compose**: dstack's deployment manifest format, embedding docker-compose.yaml and security config. +- **VMM Console**: Web UI for managing deployments, logs, and CVMs. + +--- + +See the [API Reference Overview](./overview) for more sections. \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/guest-agent.mdx b/docs/api-reference/api-sub-docs/guest-agent.mdx new file mode 100644 index 00000000..84025383 --- /dev/null +++ b/docs/api-reference/api-sub-docs/guest-agent.mdx @@ -0,0 +1,70 @@ +--- +title: "Guest Agent RPC API" +description: "Endpoints and usage for the dstack Guest Agent RPC API inside CVMs." +--- + +[← Back to API Reference Overview](./overview) + +# Guest Agent RPC API + +The Guest Agent runs inside each dstack CVM, providing cryptographic, attestation, and key management services via a Unix domain socket. + +- **Socket:** `/var/run/dstack.sock` +- **Access:** Use the `--unix-socket` flag with curl or mount the socket in your container. + +## Docker Compose Integration + +```yaml +services: + myservice: + image: your-image + volumes: + - /var/run/dstack.sock:/var/run/dstack.sock +``` + +## Endpoints + +### 1. `/GetTlsKey` +- Derives a cryptographic key and returns a TLS certificate chain for RA-TLS. +- **Request:** + - `subject` (string) + - `alt_names` (array of strings) + - `usage_ra_tls` (boolean) + - `usage_server_auth` (boolean) + - `usage_client_auth` (boolean) +- **Response:** + - `key` (PEM string) + - `certificate_chain` (array of PEM strings) + +### 2. `/GetKey` +- Generates an ECDSA key (k256) for Ethereum or other uses. +- **Request:** + - `path` (string) + - `purpose` (string) +- **Response:** + - `key` (hex string) + - `signature_chain` (array of hex strings) + +### 3. `/GetQuote` +- Generates a TDX quote with provided report data. +- **Request:** + - `report_data` (string, max 64 bytes) +- **Response:** + - `quote` (hex string) + - `event_log` (string) + - `report_data` (hex string) + +### 4. `/Info` +- Retrieves information about the CVM instance. +- **Response:** + - `app_id`, `instance_id`, `app_cert`, `tcb_info`, `app_name`, `public_logs`, `public_sysinfo`, `device_id`, `mr_aggregated`, `os_image_hash`, `key_provider_info`, `compose_hash` + +### 5. `/EmitEvent` +- Emits an event to be extended to RTMR3 (requires Dstack OS 0.5.0+). +- **Request:** + - `event` (string) + - `payload` (hex string) + +--- + +See the [API Reference Overview](./overview) for more sections. \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/management.mdx b/docs/api-reference/api-sub-docs/management.mdx new file mode 100644 index 00000000..cc9444da --- /dev/null +++ b/docs/api-reference/api-sub-docs/management.mdx @@ -0,0 +1,31 @@ +--- +title: "Management APIs" +description: "HTTP endpoints for monitoring, logs, and the VMM Management Console." +--- + +[← Back to API Reference Overview](./overview) + +# Management APIs + +## Guest Agent HTTP Endpoints + +- **Dashboard:** `/` + Web dashboard with CVM info, containers, and system stats. + _Access: Requires `public_sysinfo` or `public_logs` enabled._ + +- **Metrics:** `/metrics` + Prometheus-format metrics about the guest system. + _Access: Requires `public_sysinfo` enabled._ + +- **Container Logs:** `/logs/` + Stream logs with options: `since`, `until`, `follow`, `text`, `timestamps`, `bare`, `tail`, `ansi`. + _Access: Requires `public_logs` enabled._ + +## VMM Management Console + +- **URL:** `http://localhost:9080` (configurable) +- **Features:** Deploy apps via docker-compose.yaml, view logs, manage CVMs. + +--- + +See the [API Reference Overview](./overview) for more sections. \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/overview.mdx b/docs/api-reference/api-sub-docs/overview.mdx new file mode 100644 index 00000000..3511dec9 --- /dev/null +++ b/docs/api-reference/api-sub-docs/overview.mdx @@ -0,0 +1,16 @@ +--- +title: "API Reference Overview" +description: "Glossary and entry point for dstack API endpoints, management interfaces, and SDKs." +--- + +# dstack API Reference Overview + +Welcome to the dstack API Reference. Here you'll find detailed documentation for all dstack APIs, including: + +- [Guest Agent RPC API](./guest-agent) +- [Management APIs](./management) +- [Supervisor API](./supervisor) +- [VMM Management Console](./vmm-console) +- [SDKs](./sdks) + +Each section provides endpoint details, request/response formats, and usage examples. Use this page as a glossary and navigation hub for all dstack API documentation. \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/sdks.mdx b/docs/api-reference/api-sub-docs/sdks.mdx new file mode 100644 index 00000000..aa778249 --- /dev/null +++ b/docs/api-reference/api-sub-docs/sdks.mdx @@ -0,0 +1,52 @@ +--- +title: "Official SDKs" +description: "Installation and usage for dstack SDKs in JavaScript/TypeScript, Python, Go, and Rust." +--- + +[← Back to API Reference Overview](./overview) + +# Official SDKs + +## JavaScript/TypeScript SDK + +**Install:** +```bash +npm install @phala/dstack-sdk +``` + +**Features:** +- Viem integration for Ethereum +- Solana Web3.js integration +- Environment variable encryption utilities + +--- + +## Python SDK + +**Install:** +```bash +pip install dstack-sdk +``` + +**Blockchain Integration:** +- Ethereum: `pip install "dstack-sdk[eth]"` +- Solana: `pip install "dstack-sdk[sol]"` + +--- + +## Go SDK + +**Install:** +```bash +go get github.com/Dstack-TEE/dstack/sdk/go +``` + +--- + +## Rust SDK + +Built-in as part of the core dstack components. + +--- + +See the [API Reference Overview](./overview) for more sections. \ No newline at end of file diff --git a/docs/api-reference/api-sub-docs/supervisor.mdx b/docs/api-reference/api-sub-docs/supervisor.mdx new file mode 100644 index 00000000..ff274d5f --- /dev/null +++ b/docs/api-reference/api-sub-docs/supervisor.mdx @@ -0,0 +1,26 @@ +--- +title: "Supervisor API" +description: "Process management endpoints for controlling services within dstack CVMs." +--- + +[← Back to API Reference Overview](./overview) + +# Supervisor API + +The Supervisor API manages processes inside dstack CVMs. + +## Endpoints + +- `POST /deploy` — Deploy a new process +- `POST /start/` — Start a process +- `POST /stop/` — Stop a process +- `DELETE /remove/` — Remove a process +- `GET /list` — List all processes +- `GET /info/` — Get process information +- `GET /ping` — Health check + +Each endpoint returns status and error information in a consistent format. + +--- + +See the [API Reference Overview](./overview) for more sections. \ No newline at end of file diff --git a/docs/api-reference/authentication.mdx b/docs/api-reference/authentication.mdx new file mode 100644 index 00000000..8b959318 --- /dev/null +++ b/docs/api-reference/authentication.mdx @@ -0,0 +1,332 @@ +--- +title: "API Reference" +description: "Comprehensive guide to Dstack's TEE SDK APIs, Guest Agent RPC service, and available SDKs for confidential computing." +--- + +Dstack is a **developer friendly** and **security first** SDK that simplifies deploying any containerized app into a TEE (Trusted Execution Environment). [1](#0-0) + +This reference provides detailed documentation for Dstack's APIs, including the Guest Agent RPC service, management interfaces, and available SDKs. + +--- + +## 📘 Overview + +Dstack consists of several key components: [2](#0-1) + +- **dstack-vmm**: A service running in bare TDX host to manage CVMs +- **dstack-gateway**: A reverse proxy to forward TLS connections to CVMs +- **dstack-kms**: A KMS server to generate keys for CVMs +- **dstack-guest-agent**: A service running in CVM to serve containers' key derivation and attestation requests +- **supervisor**: Process management service within CVMs + +The overall architecture enables secure deployment of containerized applications within Intel TDX (Trust Domain Extensions) environments. + +--- + +## 🔐 Authentication + +Dstack uses simple API token authentication for the VMM component when enabled: [3](#0-2) + +```toml +[auth] +enabled = false +tokens = [] +``` + +Most API interactions within CVMs occur over Unix domain sockets and do not require external authentication. + +--- + +## 🛠️ Guest Agent RPC API + +The primary API for applications running inside Dstack CVMs. The Guest Agent provides cryptographic services, attestation, and key derivation capabilities. + +### Base Connection + +The Guest Agent listens on a Unix domain socket: [4](#0-3) + +``` +/var/run/dstack.sock +``` + +All API requests should be made to this socket using the `--unix-socket` flag with curl. + +### Docker Compose Integration + +To access the Guest Agent API from your containers, mount the Unix socket: [5](#0-4) + +```yaml +services: + jupyter: + image: quay.io/jupyter/base-notebook + volumes: + - /var/run/dstack.sock:/var/run/dstack.sock +``` + +### API Endpoints + +#### 1. GetTlsKey + +Derives a cryptographic key and returns it along with its TLS certificate chain for RA-TLS: [6](#0-5) + +**Endpoint:** `/GetTlsKey` [7](#0-6) + +**Request Parameters:** [8](#0-7) + +| Field | Type | Description | +|-------|------|-------------| +| `subject` | string | The subject name for the certificate | +| `alt_names` | array of strings | List of Subject Alternative Names (SANs) | +| `usage_ra_tls` | boolean | Whether to include quote in certificate for RA-TLS | +| `usage_server_auth` | boolean | Enable certificate for server authentication | +| `usage_client_auth` | boolean | Enable certificate for client authentication | + +**Example Request:** [9](#0-8) + +**Response Format:** [10](#0-9) + +```json +{ + "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----", + "certificate_chain": [ + "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" + ] +} +``` + +#### 2. GetKey + +Generates an ECDSA key using the k256 elliptic curve for Ethereum key generation: [11](#0-10) + +**Endpoint:** `/GetKey` [12](#0-11) + +**Request Parameters:** [13](#0-12) + +| Field | Type | Description | +|-------|------|-------------| +| `path` | string | Path for the key | +| `purpose` | string | Purpose for the key (used in signature chain) | + +**Example Request:** [14](#0-13) + +**Response Format:** [15](#0-14) + +```json +{ + "key": "", + "signature_chain": [ + "", + "" + ] +} +``` + +#### 3. GetQuote + +Generates a TDX quote with given plain report data: [16](#0-15) + +**Endpoint:** `/GetQuote` [17](#0-16) + +**Request Parameters:** [18](#0-17) + +| Field | Type | Description | +|-------|------|-------------| +| `report_data` | string | Report data of max 64 bytes (padded with 0s if less) | + +**Response Format:** [19](#0-18) + +```json +{ + "quote": "", + "event_log": "quote generation log", + "report_data": "" +} +``` + +#### 4. Info + +Retrieves worker information about the CVM instance: [20](#0-19) + +**Endpoint:** `/Info` [21](#0-20) + +**Response Format:** [22](#0-21) + +```json +{ + "app_id": "", + "instance_id": "", + "app_cert": "", + "tcb_info": "", + "app_name": "my-app", + "public_logs": true, + "public_sysinfo": true, + "device_id": "", + "mr_aggregated": "", + "os_image_hash": "", + "key_provider_info": "", + "compose_hash": "" +} +``` + +#### 5. EmitEvent + +Emit an event to be extended to RTMR3 on TDX platform (requires Dstack OS 0.5.0+): [23](#0-22) + +**Endpoint:** `/EmitEvent` [24](#0-23) + +**Request Parameters:** [25](#0-24) + +| Field | Type | Description | +|-------|------|-------------| +| `event` | string | The event name | +| `payload` | string | Hex-encoded payload data | + +--- + +## 📊 Management APIs + +### Guest Agent HTTP Endpoints + +The Guest Agent also provides HTTP endpoints for monitoring and log access: [26](#0-25) + +#### Dashboard +- **Endpoint:** `/` +- **Description:** Web dashboard showing CVM information, containers, and system stats +- **Access:** Available when `public_sysinfo` or `public_logs` is enabled + +#### Metrics +- **Endpoint:** `/metrics` [27](#0-26) +- **Description:** Prometheus-format metrics about the guest system +- **Access:** Available when `public_sysinfo` is enabled + +#### Container Logs +- **Endpoint:** `/logs/` [28](#0-27) +- **Description:** Stream container logs with various formatting options +- **Parameters:** `since`, `until`, `follow`, `text`, `timestamps`, `bare`, `tail`, `ansi` +- **Access:** Available when `public_logs` is enabled + +### Supervisor API + +Process management API for controlling services within CVMs: [29](#0-28) + +**Available Endpoints:** +- `POST /deploy` - Deploy a new process [30](#0-29) +- `POST /start/` - Start a process [31](#0-30) +- `POST /stop/` - Stop a process [32](#0-31) +- `DELETE /remove/` - Remove a process [33](#0-32) +- `GET /list` - List all processes [34](#0-33) +- `GET /info/` - Get process information [35](#0-34) +- `GET /ping` - Health check [36](#0-35) + +### VMM Management Console + +Web-based management interface for VM operations: [37](#0-36) + +- **Access:** `http://localhost:9080` (configurable port) +- **Features:** Deploy applications via docker-compose.yaml, view logs, manage CVMs + +--- + +## 📦 Official SDKs + +Dstack provides official SDKs for multiple programming languages: [38](#0-37) + +### JavaScript/TypeScript SDK + +**Installation:** [39](#0-38) +```bash +npm install @phala/dstack-sdk +``` + +**Basic Usage:** [40](#0-39) + +**Features:** +- Viem integration for Ethereum [41](#0-40) +- Solana Web3.js integration [42](#0-41) +- Environment variable encryption utilities [43](#0-42) + +### Python SDK + +**Installation:** [44](#0-43) +```bash +pip install dstack-sdk +``` + +**Basic Usage:** [45](#0-44) + +**Blockchain Integration:** +- Ethereum support: `pip install "dstack-sdk[eth]"` [46](#0-45) +- Solana support: `pip install "dstack-sdk[sol]"` [47](#0-46) + +### Go SDK + +**Installation:** [48](#0-47) +```bash +go get github.com/Dstack-TEE/dstack/sdk/go +``` + +**Basic Usage:** [49](#0-48) + +### Rust SDK + +Built-in support as part of the core Dstack components. + +--- + +## 🔧 Development Tools + +### Simulator + +For local development without TDX hardware: [50](#0-49) + +```bash +git clone https://github.com/Dstack-TEE/dstack.git +cd dstack/sdk/simulator +./build.sh +./dstack-simulator +``` + +--- + +## 📝 Error Handling + +All Guest Agent API endpoints return consistent error responses: [51](#0-50) + +**HTTP Status Codes:** +- `200 OK`: Request successful +- `400 Bad Request`: Invalid request parameters +- `500 Internal Server Error`: Server-side error + +**Error Response Format:** +```json +{ + "error": "Error description" +} +``` + +--- + +## 🏗️ Architecture Notes + +### Container Deployment +Applications are deployed using docker-compose.yaml files through the VMM web interface. [52](#0-51) + +### Secret Management +Environment variables can be encrypted client-side and decrypted within the CVM before being passed to containers. [53](#0-52) + +### Network Access +Apps are accessible via dstack-gateway using domain mapping: [54](#0-53) +- `[s].` maps to port 80/443 +- `-[s].` maps to specified port + +### TDX Attestation +Applications can generate TDX quotes for remote attestation by mounting the Guest Agent socket and making API calls. [55](#0-54) + +--- + +## Notes + +This API reference covers the core Dstack TEE SDK APIs for confidential computing applications. Dstack is specifically designed for deploying containerized applications in Intel TDX environments with strong security guarantees through remote attestation and encrypted execution. + +For deployment and operational guides, refer to the main Dstack documentation and repository examples. + diff --git a/docs/community-section/community.mdx b/docs/community-section/community.mdx new file mode 100644 index 00000000..7c288791 --- /dev/null +++ b/docs/community-section/community.mdx @@ -0,0 +1,60 @@ +--- +title: "Community & Ecosystem" +description: "Engage with the dstack community, contribute to development, and access collaborative resources" +--- + +
+
+ {/* Discord */} + + 💬 + Discord + + {/* GitHub Discussions */} + + 🐙 + GitHub Discussions + + {/* Telegram */} + + 🛩️ + Telegram + +
+
+ + +# Community & Ecosystem + +The dstack community is open to anyone interested in confidential computing. You can get involved by asking questions, contributing code or docs, joining discussions, or helping with governance. We value transparency, technical skill, and collaboration. + +dstack is open source and depends on its community. We bring together people from research, industry, and independent backgrounds to solve real-world problems in confidential computing. Our goal is to connect theory and practice, and to help each other learn and build. + +If you want to help, you can: +- Join technical working groups (security, platform, hardware, docs) +- Take part in governance (steering committee, security board, community council, token holders) + +## Communication Channels + +You can reach the community through: +- Discord: chat and support +- GitHub Discussions: technical Q&A and proposals +- Telegram: quick questions and developer chat + + + diff --git a/docs/community-section/contribution.mdx b/docs/community-section/contribution.mdx new file mode 100644 index 00000000..614f83de --- /dev/null +++ b/docs/community-section/contribution.mdx @@ -0,0 +1,74 @@ +--- +title: "Contributing to dstack" +description: "It's the easiest way to deploy existing Docker applications to Trusted Execution Environments with hardware-enforced security" +--- + +## Contributing to dstack + +Contributing to dstack goes beyond code—it includes documentation improvements, security research, educational content, and community building. We recognize that expertise comes in many forms, and every contribution strengthens the ecosystem. + +To get started, follow these straightforward steps to contribute via GitHub: + +#### Fork & Star Repository + +- ⭐️ **Star the repository**: [dstack repository](https://github.com/Dstack-TEE/dstack) +- 🍴 **Fork the repository** to your GitHub account. + +#### Creating a Pull Request (PR) + +1. **Clone the forked repo:** +```bash + git clone https://github.com/YOUR_USERNAME/dstack.git + cd dstack +``` + +2. **Create a branch for your changes:** + + ```bash + git checkout -b fix/your-issue-description + ``` + +3. **Make your changes** and commit: + + ```bash + git add . + git commit -m "fix: short description of changes" + ``` + +4. **Push your branch**: + + ```bash + git push origin fix/your-issue-description + ``` + +5. **Open a PR** on the [dstack repository](https://github.com/Dstack-TEE/dstack) from your branch. Reference the relevant [issue](https://github.com/Dstack-TEE/dstack/issues) clearly in your PR description. + +#### PR Template + +Use this simple template for your PR description: + +```md +### Description +Brief summary of the change. + +### Related Issue +Link or number of the issue (e.g., closes #123). + +### Type of Change +- [ ] Bug fix +- [ ] Enhancement +- [ ] Documentation update + +### Additional Context +Any additional information here. +``` + +#### Creating Issues + +* Clearly state the problem or enhancement. +* Label appropriately: `bug`, `enhancement`, or `documentation`. +* Provide steps to reproduce if it's a bug. + +**Please allow 1-3 days for responses from core contributors.** + + diff --git a/docs/community-section/troubleshooting.mdx b/docs/community-section/troubleshooting.mdx new file mode 100644 index 00000000..e905869f --- /dev/null +++ b/docs/community-section/troubleshooting.mdx @@ -0,0 +1,165 @@ +--- +title: "Troubleshooting & Diagnostics" +description: "Common issues and solutions for troubleshooting dstack deployments" +--- + +# Troubleshooting Dstack Components and Systems + +Dstack provides a comprehensive troubleshooting framework across its components, including structured logging, diagnostic commands, web dashboards, and specific error resolution guides. + +--- + +## 🧭 Overview of Troubleshooting Framework + +- Structured CLI tools for direct diagnostics +- HTTP API endpoints for log and status access +- Web dashboards for real-time and historical monitoring +- Consistent error handling and logging patterns across all components + +--- + +## 🛠️ Troubleshooting Commands and Tools + +### VMM CLI Tool + +The primary diagnostic utility is `vmm-cli.py`, which offers: + +#### VM Management & Monitoring +- `lsvm` – List all VMs and their status +- `logs` – Show VM logs (supports `--follow` and line count options) +- `start` / `stop` / `remove` – VM lifecycle commands + +#### Resource Monitoring +- `lsimage` – List available images +- `lsgpu` – List GPUs and availability status + +--- + +### 📋 Container Log Access + +You can access container logs via HTTP endpoints with flexible parameters: + +- **Parameters:** + - `since` / `until`: Time-based filtering (e.g., `"30s"`, `"5m"`, `"2h"`, `"1d"`) + - `follow`: Continuous streaming + - `text` / `bare`: Output formatting + - `timestamps`: Include timestamps + - `ansi`: ANSI color control + +--- + +## 📑 Logging and Error Handling + +### Structured Logging + +All components use the `tracing` framework for structured logs and environment-based filtering. + +### Error Handling Patterns + +- Uses `anyhow::Result` for error handling and context propagation +- Process management reports detailed exit codes and failure states + +--- + +## 🚨 Common Errors and Resolutions + +### 1. Unix Socket CID Conflicts + +**Error:** +`vhost-vsock: unable to set guest cid: Address already in use` + +**Diagnosis:** +```bash +ps aux | grep 'guest-cid=' +```` + +**Resolution:** +Configure a new CID range in `vmm.toml` or `build-config.sh`. + +--- + +### 2. CVM Status Issues + +**Error:** +CVM status turns to `exited` immediately + +**Diagnosis:** +Check stderr output by appending `ch=stderr` to your log URL. + +**Common Cause:** +Permission denied for KVM kernel module + +**Resolution:** +Ensure the user belongs to `libvirt` and `kvm` groups. + +--- + +### 3. Guest Image Build Errors + +**Error:** +`Operation not permitted` during image building + +**Cause:** +Ubuntu 23.10+ restricts unprivileged user namespaces + +**Resolution:** + +```bash +sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0 +``` + +--- + +## 🖥️ Web Dashboard Diagnostics + +### VMM Console + +* Monitor VM status/configuration +* Real-time log viewing (supports follow) +* Manage container status +* Monitor resource utilization + +### Gateway Dashboard + +* Wireguard IP address monitoring +* Node connection status +* TLS certificate management + +--- + +## 📡 Advanced Monitoring + +### Certificate Transparency Monitoring + +The `ct_monitor` tool provides: + +* Tracking CT logs for unauthorized certificates +* Validating certs against known gateway public keys +* Alerts on certificate mismatches + +### VM Event Reporting + +Tracks: + +* Boot/shutdown progress +* Errors +* Instance info updates + +--- + +## 📂 Log File Locations & Output Redirection + +* Supervisor handles output redirection and error logs +* Automatic creation of parent log directories +* Errors are logged with full context + +--- + +## 📝 Notes + +The dstack troubleshooting system layers multiple diagnostic approaches—from CLI tools and APIs to web dashboards. Structured logging via `tracing` and consistent error handling ensure that most issues have actionable diagnostic steps and clear, documented resolutions. Both real-time and historical monitoring are supported for thorough, efficient troubleshooting. + +--- + +> **Tip:** For additional context or uncommon errors, refer to the [full deployment guides](/docs/deployment-guides/) and component-specific documentation. + diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx new file mode 100644 index 00000000..ff5f5996 --- /dev/null +++ b/docs/concepts/architecture.mdx @@ -0,0 +1,716 @@ +--- +title: "System Architecture" +description: "Deep dive into dstack's layered architecture and component interactions" +--- + +# DStack System Architecture + +This page provides a technical overview of dstack’s system architecture—detailing how each component contributes to secure, scalable, and verifiable container deployments. dstack is designed to transform standard containers into confidential workloads using hardware-backed isolation, decentralized trust, and zero-trust networking. + +Here, you’ll find a breakdown of how dstack’s components interact: from user interfaces and orchestration layers to security services and confidential VMs. The architecture emphasizes cryptographic verification at every stage, secure VM orchestration, and robust management of secrets and network boundaries. + + +### We started off by Establishing Trusted vs Untrusted Boundaries + +In this architecture, trust boundaries are established to clearly delineate which components are considered secure and which are not. Trusted systems are those whose integrity and confidentiality are maintained through hardware-based security features, such as Intel TDX, cryptographic verification, and measured boot processes. These mechanisms ensure that only authorized and verified code is executed, and that sensitive operations and data remain protected. In contrast, untrusted systems include elements like the host operating system, the hypervisor outside the trusted execution environment, network infrastructure, storage systems (regardless of encryption at rest), and external services such as DNS or certificate authorities. These components are considered untrusted because they operate outside the hardware-enforced security perimeter and may be susceptible to compromise or manipulation. The architecture is intentionally designed so that, even in the event of a breach or compromise of untrusted systems, the security and confidentiality of trusted components and their data are preserved. + +
+
+ {/* Trusted */} +
+

Trusted Components

+
    +
      + + + + + + Intel TDX Hardware Attestation +
    +
      + + + + + + Cryptographic Quote Verification +
    +
      + + + + + + Blockchain Smart Contract Consensus +
    +
      + + + + + + Hardware-derived Key Material +
    +
      + + + + + + Measured Boot and Code Integrity +
    +
+
+ {/* Untrusted */} +
+

Untrusted Components

+
    +
      + + + + + + Host Operating System +
    +
      + + + + + + Hypervisor (outside TEE boundary) +
    +
      + + + + + + Network Infrastructure +
    +
      + + + + + + Storage Systems (encrypted at rest) +
    +
      + + + + + + External DNS and Certificate Authorities +
    +
+
+
+
+ + +## Now let's Deep Dive into the dstack Architecture + +dstack’s architecture is organized into distinct layers, each with a specific role and strict security boundaries. User tools, orchestration engines, security services, and confidential VMs work together to deliver secure, auditable deployments at scale. The following sections and diagrams explain the responsibilities and interactions of each layer in detail. + + +*This diagram illustrates the layered architecture of the dstack system, showing how user-facing interfaces, orchestration and security services, confidential VM components, and core infrastructure all interact. Each arrow represents a direct communication or integration path between components, from the user's CLI, dashboard, and SDKs at the top, down to trusted hardware, secure networking, and blockchain integration at the base. The design emphasizes separation of concerns and trusted execution across every layer of the stack.* + +```mermaid +graph TB + subgraph "User Layer" + CLI[dstack CLI] + WebUI[Web Dashboard] + SDK[SDKs] + end + + subgraph "Orchestration Layer" + VMM[dstack-vmm] + SUP[Supervisor] + Gateway[dstack-gateway] + end + + subgraph "Security Layer" + KMS[dstack-kms] + RA[Remote Attestation] + PCCS[PCCS Service] + end + + subgraph "CVM Layer" + GA[dstack-guest-agent] + Docker[Docker Runtime] + Apps[Application Containers] + end + + subgraph "Infrastructure" + TDX[Intel TDX TEE] + WG[WireGuard VPN] + Blockchain[Ethereum Chain] + end + + CLI --> VMM + WebUI --> VMM + SDK --> GA + VMM --> SUP + VMM --> Gateway + Gateway --> GA + KMS --> Blockchain + GA --> Docker + Docker --> Apps + VMM --> TDX + Gateway --> WG + GA --> TDX + RA --> PCCS +``` + +## [VMM (Virtual Machine Manager) Architecture](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/vmm/src/main.rs) + +The VMM is the core orchestrator implemented in Rust that manages the complete lifecycle of Confidential VMs. + +*This expandable diagram details the internal architecture of the VMM system, highlighting the main layers and service groupings. Each component is colored by function: core VMM subsystems use varying shades of green to emphasize their role within the trusted execution environment, while external interfaces and integrations are rendered in gray or blue for visual distinction. The diagram captures key data flows and relationships—from user-facing entry points, through orchestration and resource management, to integration with external key management and API endpoints—making the hierarchy and scope of each subsystem clear at a glance.* + + VMM Internal Architecture + + + + +**Key VMM Services** ([VMM RPC API](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/vmm/rpc/proto/vmm_rpc.proto)): +The VMM exposes a comprehensive suite of services through its RPC API, enabling robust management of Confidential Virtual Machines (CVMs) throughout their entire lifecycle. This includes the ability to create, start, stop, remove, and upgrade VMs with fine-grained control, ensuring operational flexibility and reliability. The VMM continuously monitors and allocates system resources, dynamically adjusting CPU, memory, disk, and GPU assignments to meet workload demands while maintaining optimal performance and isolation. Advanced networking capabilities are provided through seamless port mapping and configurable network topologies, supporting both user-mode and bridge networking scenarios. GPU management is fully integrated, allowing for efficient discovery, allocation, and sharing of GPU resources across VMs. Additionally, the VMM handles image and configuration management, streamlining the deployment and maintenance of VM environments with consistent and reproducible settings. + +**VMM Configuration** ([vmm.toml reference](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/vmm/vmm.toml)): +VMM configuration is defined in a flexible TOML file that governs all operational parameters, allowing administrators to tailor the environment to specific requirements. The configuration supports both user-mode and bridge networking, enabling versatile connectivity options for guest VMs. It manages CID pools to facilitate secure and efficient guest communication, and provides configurable resource limits for CPU, memory, and disk to ensure fair allocation and prevent resource contention. GPU discovery and allocation are natively supported, allowing the VMM to automatically detect available GPUs and assign them to VMs as needed. To enhance reliability, the configuration also includes auto-restart capabilities, ensuring that failed VMs are automatically recovered and service continuity is maintained without manual intervention. + +## [Gateway Architecture](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/src/main.rs) + +The Gateway provides secure network access and traffic routing with automatic TLS certificate management. + +### Gateway Internal Architecture + +*This diagram presents the internal architecture of the Gateway service, organizing its core functions, networking components, and security mechanisms into distinct layers. Each service block is visually grouped according to its domain—core services, network layer, and security—to highlight separation of responsibilities. The directional arrows depict key data flows and operational dependencies, from service proxies and RPC handlers through network management (including TLS, VPN, and load balancing), to certificate automation and authentication controls. The visual layout clarifies how the Gateway orchestrates secure, reliable, and scalable connectivity across the system.* +```mermaid +graph TB + subgraph "Gateway Core Services" + Main[Main Service] + Admin[Admin Service] + Proxy[Proxy Engine] + RPC[Gateway RPC Handler] + end + + subgraph "Network Layer" + TLS[TLS Termination] + WG[WireGuard VPN] + LB[Load Balancer] + Cert[Certificate Manager] + end + + subgraph "Security" + ACME[Let's Encrypt ACME] + RA_TLS[RA-TLS Integration] + Auth[Authentication] + end + + Main --> Proxy + Admin --> Cert + Proxy --> TLS + Proxy --> WG + TLS --> ACME + RA_TLS --> Auth + WG --> LB +``` + +**[Gateway RPC Services](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/rpc/proto/gateway_rpc.proto):** +The Gateway exposes a set of RPC services that enable core networking and management functionality. These services facilitate the registration of Confidential Virtual Machines (CVMs) and the automated setup of WireGuard tunnels, ensuring secure and authenticated connectivity between components. The RPC interface also orchestrates traffic routing and load balancing, dynamically distributing network flows to optimize resource utilization and maintain high availability. Integrated ACME certificate management automates the lifecycle of TLS certificates, leveraging Let's Encrypt to provision, renew, and revoke certificates as needed for secure communications. Additionally, the Gateway provides real-time status and health monitoring endpoints, allowing for continuous observability and proactive management of gateway operations. + +### Gateway Service and Traffic Flow Diagram + +```mermaid +graph TB + subgraph "External Network" + Client["External Client"] + end + + subgraph "dstack-gateway Core Services" + ProxyService["Proxy Service"] + WGService["WireGuard Service"] + CertBot["Certificate Management"] + SyncService["Sync Service"] + AuthService["Auth Service"] + RecycleService["Recycle Service"] + end + + subgraph "Confidential VMs" + CVM1["CVM Instance 1"] + CVM2["CVM Instance 2"] + end + + Client -->|"HTTPS Request"| ProxyService + ProxyService -->|"Route Traffic"| WGService + WGService -->|"Secure Tunnel"| CVM1 + WGService -->|"Secure Tunnel"| CVM2 + + CertBot -->|"Manage Certificates"| ProxyService + SyncService -->|"Cluster State"| SyncService + AuthService -->|"Verify Apps"| ProxyService + RecycleService -->|"Cleanup Stale"| WGService +``` + +**Gateway Configuration** ([gateway.toml reference](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml)): +Gateway configuration is defined in a TOML file that specifies all operational parameters. This includes detailed WireGuard VPN tunnel settings, enabling secure encrypted channels for inter-node communication. The configuration supports automatic certificate provisioning through Let's Encrypt, streamlining the deployment and renewal of TLS certificates without manual intervention. Administrators can fine-tune proxy behavior by adjusting timeouts and buffer sizes to match workload requirements and network conditions. Furthermore, the configuration supports multi-gateway synchronization, allowing multiple gateway instances to coordinate state and provide seamless, resilient service across distributed environments. + +## [KMS (Key Management Service) Architecture](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/src/main.rs) + +The KMS handles all cryptographic operations and integrates with blockchain for decentralized authorization. + +### KMS Internal Architecture + +*This diagram outlines the internal architecture of the KMS (Key Management Service), clearly organizing its core logic, key management components, and external integrations. Each section is grouped to reflect functional boundaries: the KMS core oversees primary operations and state, the key management layer handles a variety of cryptographic keys and certificates, and the integration layer connects with external systems like blockchains and remote attestation services. The directional arrows illustrate the flow of key material and control signals between modules, clarifying how onboarding, crypto operations, and state management all interact to securely provision, store, and expose keys across the trusted environment.* + +```mermaid +graph TB + subgraph "KMS Core" + Main[Main KMS Service] + Onboard[Onboarding Service] + Crypto[Crypto Operations] + State[KMS State Manager] + end + + subgraph "Key Management" + AppKeys[App-Specific Keys] + CACerts[CA Certificates] + DiskCrypt[Disk Encryption Keys] + K256[ECDSA K256 Keys] + end + + subgraph "External Integration" + BC[Blockchain Contract] + RA[Remote Attestation] + TempCA[Temporary CA] + end + + Main --> State + Main --> Crypto + Onboard --> TempCA + Crypto --> AppKeys + Crypto --> CACerts + Crypto --> DiskCrypt + Crypto --> K256 + State --> BC + State --> RA +``` + +**KMS RPC Services:** ([see service definition in kms_rpc.proto](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/rpc/proto/kms_rpc.proto#L84)) + +The KMS exposes a comprehensive suite of RPC services designed to facilitate secure cryptographic operations and system integration. One of the core services is application key derivation, which is tightly coupled with remote attestation to ensure that keys are only provisioned to verified and trusted environments. This process leverages attestation evidence to validate the integrity and authenticity of the requesting entity before any key material is derived or released. The KMS also provides robust certificate signing and chain management capabilities, enabling automated issuance, renewal, and revocation of certificates, as well as the maintenance of certificate chains to establish trust hierarchies within the system. For secure handling of sensitive configuration data, the KMS manages environment variable encryption keys, allowing applications to encrypt and decrypt environment variables at runtime without exposing raw secrets. Integration with blockchain technology is another critical service, where the KMS interacts with smart contracts to enforce decentralized authorization policies, ensuring that only entities with valid on-chain permissions can access protected resources or perform sensitive operations. Additionally, the KMS oversees image cache management, which involves the secure storage, retrieval, and validation of container or VM images, ensuring that only attested and authorized images are deployed within the infrastructure. + +**Key Types Managed:** +(see [kms_rpc.proto message struct definition](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/rpc/proto/kms_rpc.proto#L21)) + +The KMS is responsible for managing a diverse set of cryptographic key types, each tailored to specific security requirements within the platform. It maintains the TLS CA certificate chain, which forms the foundation of trust for all TLS communications by enabling the issuance and validation of server and client certificates. For data-at-rest protection, the KMS generates and stores disk encryption keys that are used to implement full disk encryption, safeguarding sensitive data even if physical storage is compromised. To support secure environment variable handling, the KMS provisions X25519 keys, which are used for encrypting and decrypting environment variables, ensuring that secrets remain protected throughout their lifecycle. The system also manages ECDSA K256 keys, which are essential for performing Ethereum-compatible cryptographic operations, such as signing blockchain transactions or verifying signatures in decentralized applications. Finally, the KMS orchestrates the creation and management of signed key chains, which are used for trust verification across distributed components, enabling secure delegation and validation of cryptographic authority within the ecosystem. + +## Guest Agent Architecture + +[See main.rs implementation reference](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/main.rs#L200) + +The Guest Agent runs inside each CVM and provides the runtime environment for applications. + +### Guest Agent Internal Architecture + +*This diagram depicts the internal architecture of the Guest Agent, which operates inside each confidential VM (CVM) to orchestrate application runtime, container lifecycle, and security services. Core service groupings show how external and internal APIs interact with the state manager, which coordinates both application execution and cryptographic operations. Container management subsystems oversee Docker runtime, monitoring, and system health, while the security layer handles key derivation, attestation, and event logging. The flow of data and control across these modules demonstrates how the Guest Agent maintains both robust runtime orchestration and a strong security posture within the confidential computing environment.* + +```mermaid +graph TB + subgraph "Guest Agent Services" + External[External RPC] + Internal[Internal RPC] + InternalV0[Internal RPC v0] + GuestAPI[Guest API] + State[App State Manager] + end + + subgraph "Container Management" + Docker[Docker Runtime] + Monitor[Container Monitor] + Health[Health Checks] + Watchdog[Systemd Watchdog] + end + + subgraph "Security Services" + KeyDeriv[Key Derivation] + QuoteGen[TDX Quote Generation] + EventLog[Event Logging] + Attest[Attestation Service] + end + + External --> State + Internal --> State + InternalV0 --> State + GuestAPI --> State + State --> Docker + State --> KeyDeriv + State --> QuoteGen + Docker --> Monitor + Monitor --> Health + Health --> Watchdog + KeyDeriv --> Attest + QuoteGen --> EventLog +``` + +**Guest Agent RPC Services:** +[See the service definition in agent_rpc.proto](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/rpc/proto/agent_rpc.proto#L31) + +The Guest Agent exposes a set of RPC services that enable secure and flexible management of cryptographic and attestation operations within the CVM environment. These services include the derivation of TLS keys along with the automated generation of certificates, ECDSA key generation for cryptographic signing, and the production of TDX quotes with support for custom report data. Additionally, the Guest Agent is capable of emitting events to extend RTMR3 measurements, thereby supporting advanced attestation workflows, and provides comprehensive application information and status reporting to facilitate monitoring and integration with external systems. + +**Supported Key Operations** +[See full list in agent_rpc.proto →](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/rpc/proto/agent_rpc.proto#L50) + +The Guest Agent supports a range of key management operations, including path-based key derivation for hierarchical key management, certificate generation with configurable subject and alternative names, and integration with RA-TLS for remote attestation. It can issue both server and client authentication certificates as required by the application, and supports random seed-based key generation to ensure cryptographic strength and flexibility in key provisioning workflows. + +## Supervisor Architecture + +[See the main Supervisor implementation in main.rs](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/supervisor/src/main.rs#L112) + +The Supervisor is responsible for orchestrating the lifecycle of VM processes and provides a web-based management interface for operational control. It features robust process lifecycle management with PID tracking, facilitates communication through Unix domain sockets, and exposes a web API for VM control operations. The Supervisor also supports configurable logging and daemonization to suit various deployment environments, and enforces resource limits to ensure reliable and secure operation of managed virtual machines. + +## Component Interaction Flows + +### VM Deployment Flow + +```mermaid +sequenceDiagram + participant CLI as dstack CLI + participant VMM as dstack-vmm + participant SUP as Supervisor + participant KMS as dstack-kms + participant GA as Guest Agent + participant GW as Gateway + + CLI->>VMM: CreateVm(VmConfiguration) + VMM->>KMS: GetAppKey(vm_config + quote) + KMS->>VMM: AppKeyResponse(keys + certs) + VMM->>SUP: StartVM(config) + SUP->>VMM: VM Started + VMM->>GA: Configure Keys + GA->>GW: RegisterCvm(wg_pubkey) + GW->>GA: WireGuardConfig + routes + VMM->>CLI: VM ID + Status +``` + +### Request Routing Flow + +```mermaid +sequenceDiagram + participant Client + participant GW as Gateway + participant WG as WireGuard + participant GA as Guest Agent + participant App as Application + + Client->>GW: HTTPS Request + GW->>GW: TLS Termination + GW->>WG: Route via VPN + WG->>GA: Forward Request + GA->>App: Proxy to Container + App->>GA: Application Response + GA->>WG: Return Response + WG->>GW: VPN Response + GW->>Client: HTTPS Response +``` + +### Remote Attestation Flow + +```mermaid +sequenceDiagram + participant Client + participant GA as Guest Agent + participant TDX as Intel TDX + participant KMS as dstack-kms + participant BC as Blockchain + + Client->>GA: Request with Attestation + GA->>TDX: Generate Quote + TDX->>GA: Hardware-signed Quote + GA->>KMS: GetAppKey(quote) + KMS->>BC: Verify Authorization + BC->>KMS: Auth Result + KMS->>GA: Keys + Certificate + GA->>Client: Response + Proof +``` + +## Network Architecture + +### Multi-Layer Network Security + +([gateway config](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/gateway.toml#L38)) ([vmm config](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/vmm.toml#L12)) + +*This diagram provides a detailed view of the dstack multi-layer network architecture, emphasizing the layered security controls that protect communication from the public internet down to confidential workloads. Each layer is visually differentiated by shades of green, representing increasing trust and isolation as traffic flows inward. The structure ensures strict separation between external access, secure tunnels, and internal virtualized resources, while maintaining strong cryptographic guarantees at every boundary. The architecture demonstrates how network segmentation, encrypted tunneling, automated certificate management, and container-level isolation work together to create a robust and defense-in-depth security posture.* + +```mermaid +graph TB + %% Public Internet + subgraph PUB["Public Internet"] + HTTPS[HTTPS Traffic :443] + DNS[DNS Resolution] + end + + %% Gateway Layer + subgraph GATE["Gateway Layer"] + LB[Load Balancer] + TLS[TLS Termination] + ACME[ACME Certificates] + end + + %% VPN Layer + subgraph VPN["VPN Layer"] + WG[WireGuard Network] + Tunnel[Encrypted Tunnels] + end + + %% CVM Network + subgraph CVM["CVM Internal Network"] + Internal[Internal Bridge] + DHCP[DHCP Range
10.0.2.0/24] + Containers[Container Networks] + end + + HTTPS --> LB + DNS --> LB + LB --> TLS + TLS --> ACME + TLS --> WG + WG --> Tunnel + Tunnel --> Internal + Internal --> DHCP + DHCP --> Containers + + %% -- Coloring (shades of green inward) -- + style PUB fill:#e2e8f0,stroke:#a3a3a3,stroke-width:2px + style HTTPS fill:#e2e8f0,stroke:#a3a3a3 + style DNS fill:#e2e8f0,stroke:#a3a3a3 + + style GATE fill:#d1fae5,stroke:#059669,stroke-width:2.5px + style LB fill:#bbf7d0,stroke:#059669 + style TLS fill:#86efac,stroke:#059669 + style ACME fill:#dcfce7,stroke:#059669 + + style VPN fill:#6ee7b7,stroke:#047857,stroke-width:2.5px + style WG fill:#4ade80,stroke:#047857 + style Tunnel fill:#34d399,stroke:#047857 + + style CVM fill:#f0fdf4,stroke:#16a34a,stroke-width:2.5px + style Internal fill:#bbf7d0,stroke:#16a34a + style DHCP fill:#86efac,stroke:#16a34a + style Containers fill:#dcfce7,stroke:#16a34a +``` + +--- + +### Network Configuration Layers + +* **Public Layer:** + Handles all ingress from the public internet. HTTPS and DNS traffic are first received and terminated at the load balancer. This layer enforces TLS encryption at the network edge and acts as the first point of defense against external threats. + +* **Gateway Layer:** + Consists of the load balancer, TLS termination, and automated certificate management using ACME. Here, connections are securely routed and encrypted certificates are managed dynamically. The gateway strictly enforces security boundaries and forwards only authenticated, encrypted traffic deeper into the stack. + +* **VPN Layer:** + All internal traffic passes through a dedicated WireGuard VPN overlay. Encrypted tunnels are automatically provisioned for both host-to-host and host-to-VM traffic, providing confidential communication even across untrusted networks. This adds a strong cryptographic layer, ensuring that no data traverses the underlying infrastructure unprotected. + +* **CVM Internal Network:** + At the heart of the system, the internal network segments VM and container workloads via isolated virtual bridges and DHCP-managed subnets. Each confidential VM (CVM) and its containers receive unique, securely allocated addresses, minimizing lateral movement and further compartmentalizing resources. Communication between workloads is strictly controlled and isolated from public and management networks. + +* **Security:** + All network segments are encrypted and authenticated, with certificates managed automatically and VPN keys rotated regularly. Only explicitly authorized endpoints can communicate, and all management, orchestration, and application data flows are cryptographically verified at each boundary. + +--- + +**The layered network architecture implements mandatory isolation between public, management, and confidential computing environments. Each segment is cryptographically protected, with no direct access permitted across boundaries. Only authenticated and authorized traffic is allowed to traverse between layers, minimizing attack surface and enforcing defense-in-depth.** + + + +--- + +## Security Architecture + +### Defense in Depth Model + +1. Foundational Trust Chain + +```mermaid +flowchart LR + A[TEE Hardware
Protection] + B[Encrypted
Memory] + C[Measured Boot
& Attestation] + D[Remote Quote
Verification] + + A --> B --> C --> D + + style A fill:#e6f0fa,stroke:#2b6cb0,stroke-width:2px + style B fill:#e6f0fa,stroke:#2b6cb0,stroke-width:2px + style C fill:#e6f0fa,stroke:#2b6cb0,stroke-width:2px + style D fill:#e6f0fa,stroke:#2b6cb0,stroke-width:2px +``` + + + +2. Derived Controls & Runtime Protections + +```mermaid +flowchart LR + E[Key Derivation
& Storage] + F[Disk Encryption] + G[TLS /
WireGuard] + H[Container
Isolation] + + E --> F --> G --> H + + style E fill:#eafbe7,stroke:#258a38,stroke-width:2px + style F fill:#eafbe7,stroke:#258a38,stroke-width:2px + style G fill:#eafbe7,stroke:#258a38,stroke-width:2px + style H fill:#eafbe7,stroke:#258a38,stroke-width:2px +``` + + + + +## Deployment Topologies + +### Single Host Development + +```mermaid +flowchart TB + subgraph DevHost["Development Host"] + VMM["VMM
:8080"] + Gateway["Gateway
:8082"] + KMS["KMS
:8081"] + Supervisor["Supervisor
UDS"] + + subgraph CVMs["CVM Instances (TDX)"] + Agent1["Agent
:8090"] + Agent2["Agent
:8090"] + end + end + + VMM --> CVMs + Gateway --> CVMs + KMS --> CVMs + Supervisor --> CVMs + + %% Coloring + style DevHost fill:#e9f9ee,stroke:#4ade80,stroke-width:2px + style VMM fill:#bbf7d0,stroke:#059669,stroke-width:2px + style Gateway fill:#bbf7d0,stroke:#059669,stroke-width:2px + style KMS fill:#bbf7d0,stroke:#059669,stroke-width:2px + style Supervisor fill:#bbf7d0,stroke:#059669,stroke-width:2px + style CVMs fill:#dcfce7,stroke:#34d399,stroke-width:2px + style Agent1 fill:#a7f3d0,stroke:#059669,stroke-width:2px + style Agent2 fill:#a7f3d0,stroke:#059669,stroke-width:2px + +``` + +### Production Multi-Host Cluster + +```mermaid +flowchart LR + subgraph Host1["Host 1"] + VMM1["VMM
+ CVMs"] + WireGuard1["WireGuard
Endpoints"] + end + subgraph Host2["Host 2"] + Gateway2["Gateway
+ CVMs"] + LB["Load Balancer
TLS Termination"] + end + subgraph Host3["Host 3"] + KMS3["KMS
+ CVMs"] + Blockchain["Blockchain
Integration"] + end + + WireGuard1 -- traffic --> LB + LB -- traffic --> Blockchain + + %% Visual separation of hosts and components + style Host1 fill:#e5e7eb,stroke:#a3a3a3,stroke-width:2px + style VMM1 fill:#bbf7d0,stroke:#059669,stroke-width:2px + style WireGuard1 fill:#d1fae5,stroke:#10b981,stroke-width:2px + + style Host2 fill:#e5e7eb,stroke:#a3a3a3,stroke-width:2px + style Gateway2 fill:#bbf7d0,stroke:#059669,stroke-width:2px + style LB fill:#f9fafb,stroke:#7dd3fc,stroke-width:2px + + style Host3 fill:#e5e7eb,stroke:#a3a3a3,stroke-width:2px + style KMS3 fill:#bbf7d0,stroke:#059669,stroke-width:2px + style Blockchain fill:#bae6fd,stroke:#0369a1,stroke-width:2px + +``` + +## Performance Characteristics & Resource Management + +*Understanding the performance and resource constraints of the dstack platform is essential for capacity planning, debugging, and cost modeling. This section summarizes the most important real-world timings and system limits, so operators and users know what to expect and where scaling thresholds or bottlenecks might arise. All configuration and reference links are included for full transparency and reproducibility.* + +--- + +
+
+

Typical Performance Metrics

+
    +
  • CVM boot time: 30–60s (with TDX attestation)
    • +
  • Container start: 2–5s (Docker runtime)
    • +
  • Quote generation: 50–100ms (TDX hardware)
    • +
  • Key derivation: 10–50ms (KMS operations)
    • +
  • Network latency: 1–5ms (WireGuard overhead)
    • +
  • TLS handshake: 100–200ms (with RA-TLS verification)
    • +
+
+
+

Key Resource Limits & Scaling

+ +
+
+ +--- + +### Why This Matters + +* **Operational predictability:** These figures help set user expectations for startup, scaling, and workload responsiveness. +* **Capacity planning:** Knowing resource ceilings and timing enables efficient host sizing and better cost modeling for clusters. +* **Debugging and troubleshooting:** Outliers and anomalies are easier to spot when typical timings and quotas are known upfront. +* **Transparent configuration:** Direct links to source config files ensure reproducibility and clarity for security and compliance review. + +> *Reviewing these characteristics is essential for operators, architects, and developers to make informed choices about deploying, scaling, and troubleshooting confidential workloads on dstack.* + + +## Next Steps + +Now that you understand the comprehensive architecture: + + + +The dstack architecture provides enterprise-grade security through: +- **Hardware-based Isolation**: Intel TDX for memory encryption and attestation +- **Cryptographic Verification**: End-to-end quote verification and key derivation +- **Zero-trust Networking**: WireGuard VPN with TLS termination +- **Decentralized Trust**: Blockchain-based authorization without central authority +- **Container Security**: Isolated execution environments within TEEs + +Learn more about our [Security Model](/docs/concepts/security-model) and [Core Components](/docs/concepts/core-components). + diff --git a/docs/concepts/basic-components.mdx b/docs/concepts/basic-components.mdx new file mode 100644 index 00000000..9f21ff40 --- /dev/null +++ b/docs/concepts/basic-components.mdx @@ -0,0 +1,124 @@ +--- +title: "High Level Component Overview" +--- + +The **dstack** framework is built from several foundational components that work together to provide a secure, confidential cloud runtime. Each component plays a specific role in establishing a Trusted Execution Environment (TEE) for containerized applications. Collectively, these components form a layered architecture that enables Docker-based workloads to run inside Intel TDX-powered Confidential VMs (CVMs) with strong isolation, attestation, and encrypted I/O by default. (For a broader architectural overview, see the [architecture concepts](/docs/concepts/architecture) documentation.) Below, we introduce each core component and explain how they integrate to deliver a zero-trust deployment platform: + +**dstack-vmm** – The virtualization manager that runs on a bare-metal Intel TDX host, responsible for launching and managing CVMs (Confidential VMs). It leverages Intel TDX hardware features to instantiate each CVM as an isolated trust domain: all memory within a CVM is encrypted and inaccessible to the host OS or hypervisor, and the CVM's boot process is cryptographically measured to produce an attestation of its integrity. In effect, **dstack-vmm** orchestrates secure VM life-cycle operations, ensuring every deployed application VM starts in a known-good state and can provide proof of its TEE-backed integrity. + +**dstack-gateway** – A network gateway (reverse proxy) that exposes services running inside CVMs to the outside world via secure connections. It forwards incoming TLS (HTTPS) connections from clients to the appropriate CVM, acting as a conduit that upholds end-to-end confidentiality. The **dstack-gateway** automatically handles TLS termination using certificates that are **cryptographically bound to the attestation identity of the CVM** (RA-TLS). This ensures that only the intended TEE-resident service can present a valid certificate for its address, giving clients assurance they are communicating with a genuine confidential service and enforcing Zero Trust principles for incoming traffic. + +**dstack-kms** – A Key Management Service that derives and provides cryptographic keys for CVMs in a decentralized, trust-minimized way. Instead of storing static secrets, **dstack-kms** generates a unique *Root Key* for each application instance based on its identity (such as code, configuration, or image hash). From this root, the KMS deterministically derives all other necessary keys (for data encryption, integrity checks, etc.), delivering them on-demand to the requesting CVM after verifying it is running on authentic TEE hardware. This **decoupling of secret generation from specific TEE instances** allows encrypted state to be safely migrated across machines or cloud providers. The KMS can also implement key rotation and versioning policies, and is typically hardened and distributed to avoid any central point of failure. + +**dstack-guest-agent** – A lightweight agent process that runs inside each CVM, serving as the trusted overseer for the application's runtime. The guest agent (sometimes called `tappd`) sets up the in-VM environment and mediates all security-sensitive requests from application containers. It handles **remote attestation** and secret retrieval: when a CVM boots, the agent gathers the attestation quote from the TEE and uses it to request keys from dstack-kms, supplying those keys to container processes without ever exposing them outside the enclave. The agent also assists the dstack-gateway in establishing RA-TLS connections by generating attestation-bound TLS key material and certificates from within the enclave. Overall, **dstack-guest-agent** acts as the in-enclave security coordinator, ensuring the application inside the CVM can attest its trustworthiness and securely obtain the resources it needs. + +**meta-dstack** – A Yocto-based build layer that produces the minimal, secure guest OS image used inside the CVM. Rather than relying on a general-purpose VM image, **meta-dstack** provides a purpose-built, hardened environment for confidential containers. It includes only the essential kernel, system libraries, and dstack runtime components, minimizing the attack surface. The resulting OS (sometimes called **dstack-os**) serves as a **hardware abstraction layer** between the application containers and the TEE hardware, and is configured with security best practices out of the box. By using meta-dstack, every CVM launched by dstack-vmm starts with a vetted, trustable software stack, reducing the complexity of building confidential apps. + +--- + +# Basic Component Flow + +```mermaid +graph TB + subgraph "External" + USER[Users/Clients] + DEV[Developer] + end + + subgraph "Host Infrastructure" + VMM[dstack-vmm
VM Orchestrator] + GW[dstack-gateway
HTTPS Gateway] + end + + subgraph "KMS CVM" + KMS[dstack-kms
Key Management] + end + + subgraph "Application CVM" + OS[dstack-os
Secure Foundation] + AGENT[dstack-guest-agent
Container Manager] + APPS[Your Applications] + end + + %% Deployment Flow + DEV -->|Deploy App| VMM + VMM -->|Create CVM| OS + OS -->|Start| AGENT + AGENT -->|Request Keys| KMS + KMS -->|Provide Keys| AGENT + AGENT -->|Launch| APPS + + %% Runtime Flow + USER -->|HTTPS Requests| GW + GW -->|Secure Tunnel| AGENT + AGENT -->|Route to| APPS + + %% Management + VMM -.->|Manage| OS + VMM -.->|Register Routes| GW + + classDef cvm fill:#e1f5fe + classDef trusted fill:#f3e5f5 + classDef external fill:#fff3e0 + + class OS,AGENT,APPS,KMS cvm + class KMS trusted + class USER,DEV external +``` + +*The above Mermaid diagram illustrates how the basic components interconnect during an application deployment.* Starting from the **developer's application code** (packaged as one or more containers), dstack's tooling builds a specialized CVM image and hands it off to the **dstack-vmm**, which launches the Confidential VM on a TDX-enabled host. Inside the CVM, the **dstack-guest-agent** takes control: it performs a remote attestation of the new VM and orchestrates the startup of the user's **application containers**. The guest agent communicates with the **dstack-kms** to obtain the necessary secrets (such as encryption keys), proving the CVM's trustworthiness before any sensitive material is released. Meanwhile, the **dstack-gateway** on the host is configured to forward external client requests into the CVM. When a client initiates an HTTPS connection to the service (for example, via the unique `*.dstack.host` domain for that deployment), the gateway verifies the CVM's attestation and then routes the traffic over a TLS channel that terminates inside the enclave. In this way, the application's users interact with it as they would any web service, but under the hood every request and response is confined within a secure enclave context. The diagram shows the end-to-end flow: from building the confidential image, to launching the CVM, attesting and provisioning keys, and finally serving client traffic—ensuring at each step that the code running is exactly what it should be and that data remains confidential and tamper-proof. + +## Enhanced Deployment Flow + +```mermaid +sequenceDiagram + participant VMM + participant KMS + participant Gateway + participant CVM as "Confidential VM" + participant Agent as "Guest Agent" + + VMM->>KMS: Initialize KMS service + VMM->>Gateway: Configure gateway routing + VMM->>CVM: Boot CVM with dstack-os + CVM->>CVM: tdxctl SetupFde (Full Disk Encryption) + CVM->>Agent: Start guest agent + Agent->>KMS: Request app keys with attestation + KMS->>Agent: Provide keys after verification + Agent->>Gateway: Register CVM with public key + Gateway->>Agent: Provide WireGuard config + Agent->>Agent: Deploy user containers +``` + +With the core components in place, deploying an application with dstack involves a sequence of steps that **enhance the traditional cloud deployment flow with additional security checkpoints**. In a typical scenario, a developer begins with a containerized application (for example, a set of Docker containers defined via Docker Compose) and ends up with that application running in a confidential environment accessible to end-users. The process below describes this flow in a narrative form, demonstrating how dstack automates secure deployment: + +**Image Preparation and CVM Launch:** The journey starts by converting the developer's container image(s) into a Confidential VM image. Using the dstack CLI and the meta-dstack build system, the containers are bundled with the minimal OS and TEE runtime to produce a sealed CVM disk image. This image includes the application payload along with all dstack-enabling components (attestation libraries, guest agent, etc.), ready to run on a TDX-capable machine. The **dstack-vmm** then boots up a new CVM instance from this image on a bare-metal host. During this boot, the Intel TDX hardware creates a measured environment: it validates the integrity of the VM's firmware, kernel, and software stack, and generates a cryptographic quote (attestation) that reflects this exact state. By the time the CVM is live, we have a fully isolated virtual machine that is cryptographically bound to the expected software—essentially, the application is now running inside an enclave whose identity can be verified by external parties. + +**In-TEE Initialization and Attestation:** Once the Confidential VM is running, the **dstack-guest-agent** inside it springs into action. The guest agent first performs a remote attestation handshake: it collects the attestation quote from the TDX module (which proves the CVM's identity and secure state) and prepares it for consumption by external services. It then registers the new enclave instance with the rest of the dstack system. At this stage, the guest agent is effectively vouching for the VM, asserting to the outside world (and to other dstack components) that "this VM is indeed running the intended code inside a genuine TEE." With a valid quote in hand, the **dstack-guest-agent** proceeds to launch the user's application containers within the CVM. These containers now operate in a protected memory space, using the pared-down OS provided by meta-dstack, and are unable to break TEE isolation or access anything outside the enclave. The guest agent manages the container lifecycle (similar to how a container runtime or init system would), ensuring the application services come online within the secure environment. + +**Key Provisioning and Secret Injection:** A critical part of the flow involves provisioning secrets to the newly started application. As the containers initialize, they may need encryption keys (for sealing data to disk, encrypting communications, or other sensitive config like API keys). Rather than embedding secrets beforehand, dstack retrieves them on the fly from its KMS. The **dstack-guest-agent**, using the attestation evidence, sends a request to **dstack-kms** for the application's keys. The KMS service verifies the attestation report—checking that the request truly comes from an enclave running the expected code—and then uses the application's identity (such as a hash of the container image or a deployment ID) to deterministically derive the required secrets. These secrets (for example, a disk encryption key and any runtime credentials) are **never exposed in plaintext outside the TEE**: the KMS transfers them over an encrypted channel directly into the CVM's guest agent. Upon receiving the keys, the guest agent loads them into the appropriate places: it might unlock an encrypted volume inside the VM, mount a filesystem, or pass a key to the application via an environment variable or file, all within the enclave's confines. This on-demand key derivation means that even if the image or host were intercepted earlier, it contained no useful secret – the keys materialize only after the enclave proves itself. Moreover, because the keys are derived and not arbitrarily chosen, the same application code will always get the same secret on any host (facilitating features like data migration and multi-region deployment), yet an attacker cannot guess or misuse those secrets without the correct attestation. + +**Secure Service Exposure:** At this point, the application is up and running inside a CVM, with its data protected at rest and its integrity vouched for. The final step in the deployment flow is making the application accessible to users in a secure manner. This is where **dstack-gateway** comes into play. As soon as the CVM is launched and attested, the dstack system coordinates with the gateway to configure a public endpoint for the application. Each deployed service is typically assigned a unique subdomain (for example, an auto-generated hash or ID under the `dstack.host` domain) so that it can be reached via the internet. The **dstack-gateway** either obtains a TLS certificate for that domain or uses an ephemeral certificate generated by the enclave, embedding the CVM's attestation into the certificate via RA-TLS. In either case, the gateway ensures that any client connecting over HTTPS will negotiate a TLS session that is cryptographically linked to the CVM's identity. In practical terms, when a user visits the application's URL, the gateway will forward the incoming TLS connection directly into the CVM (either by acting as an SNI router in TLS passthrough mode, or by terminating TLS after verifying the enclave's certificate). The result is that the TLS handshake itself attests the enclave: a client can be presented with a certificate chain proving the server is a legitimate TEE instance, and the gateway will only route traffic to the CVM if that verification passes. All HTTP requests from the user are thus handled by the application inside the enclave, and responses travel back the same way, with the gateway simply relaying encrypted data. This **RA-HTTPS flow** gives end-to-end encryption with confidentiality and integrity guarantees that extend into the application's runtime. The user experiences a standard HTTPS connection, but behind the scenes dstack has layered in additional trust verification. + +**Completion and Continuous Trust:** After the above steps, the deployment is complete: the developer's application is running as a confidential service. From the developer's perspective, they wrote a containerized app and specified it should run on dstack; dstack then automated everything else—provisioning a secure VM, attesting it, injecting secrets, and exposing a secure endpoint. The "enhanced" nature of this deployment flow lies in the invisible security measures taken throughout. At no point does untrusted code execute, and at no point can data be accessed without proper attestation. Even after deployment, these guarantees continue: the dstack-gateway can periodically or continuously verify attestation quotes from the CVM (for instance, if the VM restarts or after a certain time interval, new quotes can be checked) and the dstack-kms can issue rotated keys if needed. If the application or the CVM needs to be updated, the process can be repeated, with the assurance that any change in code will produce a different measurement, and thus would not be trusted by KMS or gateway until explicitly approved. In summary, the deployment flow not only launches your application but does so in a way that **each stage is fortified by cryptographic trust** – from build time, to boot time, to run time, and to user access. + +## Built-In Security Subsystems in Dstack Components + +Beyond the overall flow, it's important to understand how **each dstack component incorporates its own secure sub-components or mechanisms** to enforce the platform's stringent security model. Dstack's architecture follows a defense-in-depth strategy: every layer, from hardware up to the application, includes features to mitigate threats and ensure that no single compromise breaks the chain of trust. Below, we delve into how each component is designed with security in mind: + +**dstack-vmm (Secure Enclave Orchestration):** The VMM that controls CVMs is tightly coupled with Intel's TDX technology to provide hardware-enforced isolation. When **dstack-vmm** creates a new CVM, it utilizes Intel TDX to configure the VM as a Trust Domain (TD), meaning the CPU will automatically encrypt all memory pages of the CVM and isolate them from any other software on the host. This protects the enclave's runtime state from a malicious or compromised host OS/hypervisor. Additionally, the VMM initiates the TDX measured launch process, which records hashes of the CVM's firmware, bootloader, kernel, and application stack into TDX's secure registers (RTMRs). These measurements form the basis of the CVM's attestation report. Only if the measurements match expected values (i.e. the VM is running an approved software stack) will the attestation verification succeed. By anchoring trust in the CPU's silicon and microcode, **dstack-vmm** ensures that even if an attacker had root access on the host, they could not inspect or tamper with the confidential workload inside the CVM. The VMM itself is kept as minimal as possible and runs with hardened settings on the host; it primarily just launches and tears down VMs, deferring all business logic to in-VM agents so as to minimize its own attack surface. + +**meta-dstack (Hardened Base Image):** The security of the entire system also hinges on the integrity of the guest OS that runs inside the enclave. **meta-dstack** addresses this by producing a **minimal, read-only base image** that is pre-configured for security. This image (dstack's custom OS) is built using a reproducible process (Yocto), allowing its binaries to be independently verified and preventing supply-chain tampering. It includes a custom init process that immediately starts the dstack-guest-agent and application containers, and it excludes unnecessary services or drivers that could introduce vulnerabilities. There are no default login shells or SSH servers running in the CVM, eliminating the risk of an attacker gaining interactive access. Critical binaries and scripts in the image are measured as part of the TDX attestation, so if anyone altered the OS or dstack-agent, the change would be detected. Furthermore, **meta-dstack** enables full disk encryption within the CVM using keys from dstack-kms, so even if an attacker somehow obtained a snapshot of the VM's disk, it would be unintelligible. By controlling the contents of the guest OS, meta-dstack establishes a trusted computing base inside the enclave. The design philosophy is that the OS layer should be **"intrinsically secure and verifiable, with no administrative backdoors"**, which significantly reduces the chance of misconfiguration and ensures that the CVM's software environment remains trustable. + +**dstack-guest-agent (Enclave Attestation & Enforcement):** Running withinside the secure confines of the CVM, the **guest agent** is effectively the **brains of in-enclave security**. It is built with components like the TDX attestation libraries (`tdx-attest`) and RA-TLS support (`ra-tls`, `ra-rpc`), which allow it to perform cryptographic operations tied to the enclave's identity. One of the key secure sub-components of the guest agent is the attestation quote generator: it interfaces with the TDX module to produce an attestation report that is cryptographically signed + + +by the CPU (via the Intel EPID or DCAP attestation scheme). The agent then formats this report for consumption by external services, bundling it into requests to dstack-kms or presenting it via TLS certificates to clients. The **RA-TLS certificate module** within the guest agent deserves special mention: it generates a private key and X.509 certificate signing request (CSR) inside the enclave and embeds the attestation quote into a certificate extension. This CSR can be used to obtain a certificate from a CA (which in Phala's system is automated by a built-in Certbot service for the gateway), or for a self-signed certificate that clients explicitly trust. In either case, the result is that the enclave proves ownership of a keypair that's bound to its secure state. The guest agent's design ensures that **no sensitive operation occurs without attestation**. For instance, if the application container tries to fetch a secret, the agent will only fulfill that request after it has attested to KMS and obtained the key. If the application tries to open a listening socket, the agent can enforce that only TLS connections with the proper certificate are used (or coordinate with the gateway to do so). Additionally, the guest agent runs with the least privilege necessary inside the VM and is isolated from the application's workload (for example, running as a separate process, possibly with stronger privileges to interact with TEE device drivers, but not exposed to external network except through defined channels). This separation means even if the application were compromised by an exploit, the attacker would still have to bypass the guest agent's controls to extract secrets or break TEE bounds. + +**dstack-gateway (Zero-Trust Networking):** The **gateway** component is the guardian at the network frontier, embedding Zero Trust principles into external connectivity. One of its core security sub-components is the **RA-TLS verification engine**. When the gateway proxies a connection to a CVM, it uses an RA-TLS library to validate the TLS certificate presented by the CVM's enclave (or it presents an attestation-bound certificate to the client on the CVM's behalf, depending on the mode). Essentially, the gateway will only establish or forward a connection if it can confirm the server on the other end is an attested enclave matching the expected measurement. To facilitate this, dstack-gateway works hand-in-hand with the guest agent: for example, the guest agent might supply a signed certificate to the gateway, and the gateway's job is to advertise that cert to clients (via standard TLS) and/or to verify it continuously. The gateway also incorporates a **certificate management sub-component** (built atop Let's Encrypt's ACME protocol via an internal Certbot tool) which automates obtaining TLS certificates for the human-friendly domain names of services. These certificates are issued only after the gateway proves to the CA that it controls the domain, and they might be short-lived. The combination of attestation-backed internal certificates and public CA-issued certificates means that even traditional web browsers (which require standard CAs) can be used to access enclaves securely, without custom plugins. Additionally, the gateway is hardened to prevent common web entry-point attacks: it can enforce host-based routing (ensuring one deployment can't impersonate another's domain), it terminates or forwards connections in a way that an eavesdropper on the host cannot man-in-the-middle the traffic, and it exposes only a minimal API (just forwarding) to the outside. In dstack's security model, the gateway is not fully trusted by the enclaves—it's more of a broker that must itself verify attestation. Should the gateway be compromised, it could not silently connect users to a fake service because it wouldn't have a valid enclave certificate to use. In summary, **dstack-gateway** embeds a policy of *"never trust, always verify"* for network traffic, ensuring that clients and enclaves are mutually authenticated at the cryptographic level before any data flows. + +**dstack-kms (Distributed Trust Anchor):** As the provider of keys and secrets, **dstack-kms** is arguably the most security-critical component, and it's architected with multiple safeguards accordingly. First, the KMS never stores plaintext keys long-term; instead, it employs a **deterministic key derivation** scheme. The secret derivation function (a secure cryptographic hash or KDF) takes inputs like the application's identity, possibly a deployment-specific seed, and (if policy dictates) recent blockchain randomness or other entropy, to yield the Root Key. This means that if the KMS service is down, it can recreate keys on restart exactly as before, but if an attacker steals the KMS database, they get no usable secret material (since the keys aren't simply sitting there). Second, dstack-kms is often backed or controlled by a blockchain or decentralized consensus (in Phala's implementation, the key derivation may involve on-chain governance or seed distribution). This adds resilience: no single party, not even the cloud provider hosting the KMS, can arbitrarily issue keys to an enclave that isn't authorized. The KMS checks the enclave's attestation against a ledger of legitimate deployments – for example, it might verify that the enclave's measurement corresponds to a hash that was registered on-chain when the developer deployed the app. Only if this check passes will it derive and release keys. Third, the KMS supports **key rotation and revocation**. If a vulnerability is discovered in the application or the TEE firmware, new keys can be derived (by changing the input parameters or using an updated derivation epoch), and the old keys can be scheduled for revocation, effectively re-securing data under new secrets going forward. This feature is vital for **censorship resistance and compromise recovery**: even if an attacker somehow got hold of an old key (say by breaching a TEE at one point), they cannot decrypt new data after a rotation, nor can they easily fake a new enclave to obtain keys because the attestation verification would fail. Finally, dstack-kms is typically run in a redundant, fault-tolerant manner (and could itself potentially run in TEEs for additional security, though the current design treats it as a highly trusted external service). The protocols between KMS and the guest agent are encrypted and authenticated, and the KMS logs can be audited to detect any irregular access attempts. In essence, **dstack-kms** functions as a **decentralized root-of-trust** for the system, and its internal mechanisms ensure that secrets are only handed to the right enclaves under the right conditions, with a clear audit trail and the ability to adapt if the threat landscape changes. + +Together, these built-in security subsystems ensure that each part of dstack's infrastructure reinforces the others. The hardware-level isolation and attestation from dstack-vmm/TDX provide the foundation, the minimal OS and guest agent inside the CVM maintain the enclave's integrity and mediate access to secrets, the gateway links external interactions to internal attestation, and the KMS anchors the trust chain and manages secrets without ever creating a single point of failure. This **defense-in-depth approach** means that even if one layer were to be breached or misconfigured, the other layers would continue to protect the confidentiality and integrity of the application. For developers and users, the end result is a cloud deployment platform where strong security is not an afterthought but an intrinsic quality of the runtime. Every request, every byte of data, and every management operation is checked and secured at multiple levels. For further details on the security rationale and threat model behind these components, please refer to the [dstack security model](/docs/concepts/security-model) documentation, which delves into how trust is established and maintained throughout the system. + + diff --git a/docs/concepts/core-gateway.mdx b/docs/concepts/core-gateway.mdx new file mode 100644 index 00000000..6de2c1e1 --- /dev/null +++ b/docs/concepts/core-gateway.mdx @@ -0,0 +1,187 @@ +--- +title: "Gateway Core" +description: "explains the operational features, security mechanisms, and configuration of the dstack-gateway component, including its role in TLS termination, WireGuard VPN management, domain-based routing, and integration with cluster synchronization and authorization services." +--- + + +# dstack-gateway Operational Features + +The dstack-gateway component includes comprehensive operational capabilities designed to maintain robust security, automatic cleanup, and enhanced observability within dstack deployments. For automated cleanup and maintenance, the gateway continuously monitors WireGuard handshake activity to efficiently **remove stale CVM instances**, ensuring optimal resource usage. + +It proactively manages **gateway node cleanup** to maintain seamless synchronization across distributed clusters. WireGuard configurations are automatically updated, providing stable networking without manual intervention, and connections are systematically recycled every five minutes, enforcing a maximum timeout limit of 10 hours to preserve both security and system efficiency. + +Security and authorization within the gateway are rigorously enforced. It mandates **remote attestation verification for CVM registration**, verifying the integrity and identity of each confidential VM instance at launch. + +Additionally, integration with the **KmsAuth contract** strengthens application authorization cryptographically, guaranteeing that only legitimate deployments receive necessary keys and credentials. Active **TLS certificate transparency monitoring** prevents unauthorized certificate issuance, while the management of **CAA records** restricts certificate authorities, significantly mitigating risks associated with unauthorized or compromised certificates. + +For effective monitoring and observability, the gateway provides real-time tracking of connection statistics, offering immediate insights into network health and usage patterns. CVM instance health is assessed through regular WireGuard handshake checks, enabling rapid identification and resolution of potential connectivity issues. Additionally, the system monitors certificate expiration closely, issuing proactive alerts to avoid service disruptions due to expired certificates. Continuous monitoring of cluster synchronization status further ensures that distributed deployments remain reliable, coordinated, and resilient across diverse operational scenarios. + + +# dstack-gateway Implementation + +The dstack-gateway is a reverse proxy and networking component that handles TLS termination, WireGuard VPN connections, and traffic routing between external clients and Confidential Virtual Machines (CVMs). [5](#0-4) + + +### Advanced Routing Configuration + +The gateway uses sophisticated domain-based routing with the following patterns: [6](#0-5) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PatternRouting LogicTLS ModeDefault Port
<app-id>.domain.comDirect app routingTLS Termination80
<app-id>-<port>.domain.comCustom port routingTLS TerminationSpecified port
<app-id>s.domain.comTLS passthroughTLS Passthrough443
<app-id>-<port>s.domain.comCustom port with TLS passthroughTLS PassthroughSpecified port
custom.domain.comDNS TXT lookup: `_dstack-app-address`TLS PassthroughFrom TXT record
+ +#### Gateway Confirguation -- Detailed Example +```toml +# gateway.toml - Production Configuration for dstack-gateway +# The dstack-gateway is a reverse proxy and networking component that handles +# TLS termination, WireGuard VPN connections, and traffic routing between +# external clients and Confidential Virtual Machines (CVMs) + +# Rocket web server configuration - controls the HTTP server that handles requests +workers = 8 # Number of worker threads for handling HTTP requests +max_blocking = 64 # Maximum number of blocking tasks that can run concurrently +keep_alive = 10 # HTTP keep-alive timeout in seconds +log_level = "info" # Logging level (trace, debug, info, warn, error) +port = 8000 # Port for the main HTTP server (RPC and management interface) + +[core] +# Core gateway configuration settings +state_path = "/data/gateway-state.json" # Path to store gateway state and CVM registrations +set_ulimit = true # Automatically set soft ulimit to hard ulimit for file descriptors +rpc_domain = "gateway.example.com" # Domain name for this gateway instance (used for RPC communication) +run_in_dstack = true # Whether this gateway is running as a dstack application in a CVM + +[core.auth] +# Application authorization settings - integrates with KmsAuth contract +enabled = true # Enable application authorization checks +url = "https://kms.example.com/app-auth" # URL of the KmsAuth service for verifying app permissions +timeout = "5s" # Timeout for authorization requests + +[core.admin] +# Admin interface configuration - provides management dashboard and API +enabled = true # Enable the admin interface +port = 8001 # Port for the admin interface (separate from main port) + +[core.certbot] +# Automatic TLS certificate management using Let's Encrypt and Cloudflare DNS +enabled = true # Enable automatic certificate management +workdir = "/data/rproxy/certs" # Working directory for certificate storage +acme_url = "https://acme-v02.api.letsencrypt.org/directory" # ACME server URL (production Let's Encrypt) +cf_api_token = "your_cloudflare_token" # Cloudflare API token for DNS-01 challenges +cf_zone_id = "your_zone_id" # Cloudflare zone ID for the domain +auto_set_caa = true # Automatically set CAA DNS records to restrict certificate issuance +domain = "*.app.example.com" # Wildcard domain for certificate issuance +renew_interval = "1h" # How often to check for certificate renewal +renew_before_expiration = "10d" # Renew certificates this many days before expiration +renew_timeout = "5m" # Timeout for certificate renewal operations + +[core.wg] +# WireGuard VPN configuration - creates secure tunnels to CVMs +public_key = "gateway_public_key" # WireGuard public key for this gateway +private_key = "gateway_private_key" # WireGuard private key for this gateway +listen_port = 51820 # UDP port for WireGuard to listen on +ip = "10.4.0.1/16" # IP address and network for this gateway in the VPN +reserved_net = ["10.4.0.0/27"] # IP ranges reserved for gateway infrastructure (gateway IP must be in this range) +client_ip_range = "10.4.0.0/20" # IP range available for CVM clients (must be within the main network) +config_path = "/data/wireguard/wg-ds-gw.conf" # Path to WireGuard configuration file +interface = "wg-ds-gw" # Name of the WireGuard network interface +endpoint = "203.0.113.10:51820" # Public endpoint (IP:port) where this gateway can be reached + +[core.proxy] +# TLS proxy configuration - handles HTTPS termination and routing +cert_chain = "/data/rproxy/certs/live/cert.pem" # Path to TLS certificate chain file +cert_key = "/data/rproxy/certs/live/key.pem" # Path to TLS private key file +base_domain = "app.example.com" # Base domain for application routing (apps accessible as .app.example.com) +listen_addr = "0.0.0.0" # IP address to bind the HTTPS proxy to +listen_port = 443 # Port for HTTPS traffic (standard HTTPS port) +agent_port = 8090 # Port used by CVM agents for communication +connect_top_n = 3 # Number of CVM instances to try connecting to (for load balancing) +app_address_ns_prefix = "_dstack-app-address" # DNS TXT record prefix for service discovery + +[core.proxy.timeouts] +# Timeout configuration for proxy connections - affects performance and reliability +connect = "5s" # Timeout for establishing connection to target CVM +handshake = "5s" # Timeout for TLS handshake or SNI extraction +cache_top_n = "30s" # How long to cache the list of top N CVM instances +data_timeout_enabled = true # Enable data transfer timeouts (may impact performance if disabled) +idle = "10m" # Timeout for connections without data transfer +write = "5s" # Timeout for writing data to CVM or client +shutdown = "5s" # Timeout for gracefully shutting down connections +total = "5h" # Maximum total duration for any single connection + +[core.sync] +# Cluster synchronization configuration - enables high availability with multiple gateways +enabled = true # Enable cluster synchronization +interval = "30s" # How often to sync state with other gateways +broadcast_interval = "10m" # How often to broadcast full state to cluster +timeout = "2s" # Timeout for sync operations +my_url = "https://gateway1.example.com:8001" # This gateway's admin URL for cluster communication +bootnode = "https://bootnode.example.com:8001" # Bootstrap node URL for joining the cluster + +[core.recycle] +# Resource cleanup configuration - manages lifecycle of CVM connections +enabled = true # Enable automatic cleanup of inactive resources +interval = "5m" # How often to run cleanup operations +timeout = "10h" # How long to keep inactive resources before cleanup +node_timeout = "10m" # Timeout for individual node cleanup operations +``` + + + + + +## Next Steps + +Now that you understand Gateway networking and TLS management, continue learning about dstack's core components: + + + +### Related Topics +- [Networking](/docs/concepts/networking) - Deep dive into dstack's network architecture +- [Security Model](/docs/concepts/security-model) - Understand TLS and WireGuard security \ No newline at end of file diff --git a/docs/concepts/core-glossary.mdx b/docs/concepts/core-glossary.mdx new file mode 100644 index 00000000..6dfd9565 --- /dev/null +++ b/docs/concepts/core-glossary.mdx @@ -0,0 +1,82 @@ +--- +title: "Component Glossary" +description: "Deep dive into dstack's essential components and their roles" +--- + +# DStack Core Components Overview + +This page provides an overview of dstack's core components and guides you through understanding their technical implementation. Each component plays a crucial role in creating secure, confidential computing environments. + +For a high-level conceptual overview, start with [Basic Components](/docs/concepts/basic-components). This page focuses on the technical implementation details and how components interact. + +--- + + +## Component Responsibilities + +### Host Components (Run on Physical Host) + +**VMM (Virtual Machine Manager)** +- Orchestrates CVM lifecycle and resource allocation +- Provides RPC API, Host API, Guest API, and Web UI interfaces +- Manages VM networking, storage, and GPU passthrough +- Integrates with KMS for secure boot processes + +**Gateway (Network Proxy)** +- Handles TLS termination and WireGuard VPN connections +- Routes external traffic to CVMs using domain-based routing +- Manages certificate provisioning and renewal via Let's Encrypt +- Provides cluster synchronization for high availability + +**KMS (Key Management Service)** +- Provides enterprise-grade cryptographic services with blockchain integration +- Supports three boot modes: Non-KMS, Local-Key-Provider, and KMS +- Handles remote attestation and key distribution +- Manages certificate authority and signing operations + +### CVM Components (Run Inside Confidential VMs) + +**dstack-os (Operating System)** +- Minimal, secure Linux foundation with TDX attestation +- Provides secure boot process with UEFI and measured boot +- Handles full disk encryption initialization +- Manages system services and container runtime + +**tdxctl (TDX Control Utility)** +- Provides secure boot and encryption utilities +- Handles full disk encryption setup with LUKS +- Manages Runtime Measurement Register (RTMR) extensions +- Supports data sealing and attestation operations + +**Guest Agent (Runtime Services)** +- Manages container lifecycle using containerd +- Provides security services including attestation and key derivation +- Exposes REST API via Unix socket for application integration +- Handles registration with Gateway and KMS services + +--- + + +## DStack Implementation Path + +To understand dstack's implementation in detail, follow this recommended reading order: + +1. **[VMM Core](/docs/concepts/core-vmm)** - Start here to understand VM orchestration and lifecycle management +2. **[Gateway Core](/docs/concepts/core-gateway)** - Learn about network routing, TLS, and WireGuard VPN +3. **[KMS Core](/docs/concepts/core-kms)** - Dive into key management, attestation, and cryptographic services +4. **[Guest Agent Core](/docs/concepts/core-guest-agent)** - Understand container management and runtime services +5. **[TDXctl Core](/docs/concepts/core-tdxctl)** - Explore TDX utilities and secure boot processes +6. **[OS Core](/docs/concepts/core-os)** - Learn about the minimal secure operating system foundation + +Each component page provides detailed configuration examples, API references, and operational guidance. + +## Next Steps + + diff --git a/docs/concepts/core-guest-agent.mdx b/docs/concepts/core-guest-agent.mdx new file mode 100644 index 00000000..2d4596d1 --- /dev/null +++ b/docs/concepts/core-guest-agent.mdx @@ -0,0 +1,160 @@ +--- +title: "Guest-Agent Core" +description: "Deep dive into dstack's essential components and their roles" +--- + +# Dstack Guest Agent Implementation + +The dstack guest agent is the foundational security and runtime service component that operates within Intel TDX Confidential Virtual Machines (CVMs). It serves as the critical bridge between the trusted execution environment and application workloads, providing essential attestation, container management, and cryptographic services that form the backbone of dstack's security architecture. + +## **Guest Agent Configuration** [1](#0-0) + +```toml +# Primary guest agent configuration +[default] +# Worker thread pool configuration for handling concurrent requests +workers = 8 +# Maximum blocking operations allowed concurrently +max_blocking = 64 +# Service identification string for system logs and monitoring +ident = "Dstack guest agent" +# Temporary directory for runtime operations and file processing +temp_dir = "/tmp" +# TCP keep-alive timeout for persistent connections +keep_alive = 10 +# Logging verbosity level (trace, debug, info, warn, error) +log_level = "debug" + +# Core application and security configuration +[default.core] +# Application cryptographic keys file shared between host and guest +keys_file = "/dstack/.host-shared/.appkeys.json" +# Docker Compose configuration for application containers +compose_file = "/dstack/.host-shared/app-compose.json" +# System configuration including VM specifications and host API endpoints +sys_config_file = "/dstack/.host-shared/.sys-config.json" +# Data disk mount points to monitor for metrics and health reporting +data_disks = ["/"] + +# TDX simulation mode for development and testing environments +[default.core.simulator] +# Enable simulation mode (bypasses hardware TDX requirements) +enabled = false +# Pre-generated quote file for simulation scenarios +quote_file = "quote.hex" +# Event log file for RTMR replay verification +event_log_file = "eventlog.json" + +# Internal RPC interface (legacy tappd compatibility) +[internal-v0] +# Unix domain socket for backward compatibility with tappd clients +address = "unix:/var/run/tappd.sock" +# Socket reuse configuration for service restarts +reuse = true + +# Primary internal RPC interface for dstack components +[internal] +# Unix domain socket for secure local communication +address = "unix:/var/run/dstack.sock" +reuse = true + +# External HTTP/RPC interface for remote access +[external] +# Network interface binding for external access +address = "0.0.0.0" +# HTTP service port for dashboard and API access +port = 8090 + +# Guest API interface for host communication +[guest-api] +# VSOCK address for secure host-guest communication channel +address = "vsock:0xffffffff" +``` + +## **Guest Agent Architecture Overview** + +The dstack guest agent implements a multi-service architecture designed for high availability and security within trusted execution environments. [2](#0-1) The service operates four concurrent server components that handle different aspects of system functionality while maintaining strict security boundaries and ensuring robust operation under various operational conditions. + +**Service Initialization and Management** + +The guest agent employs a sophisticated initialization sequence that ensures all critical services are available before accepting requests. [3](#0-2) Each service component runs independently with dedicated error handling and graceful degradation capabilities, ensuring that failure in one component does not compromise the entire system's security posture or operational capability. + +**Application State Management** + +Central to the guest agent's operation is the AppState management system that maintains critical security context and configuration data. [4](#0-3) This state includes cryptographic keys, application composition configuration, certificate management clients, and VM-specific configuration that enables secure and verifiable operation within the TDX environment. + +## **Security Architecture and Attestation Services** + +**TDX Quote Generation and Verification** + +The guest agent implements comprehensive TDX attestation capabilities that enable remote parties to verify the integrity and authenticity of the execution environment. [5](#0-4) The attestation system supports both raw quote generation for low-level operations and structured quote generation with hash-based report data processing, providing flexibility for different security requirements and use cases. + +**Runtime Measurement Register (RTMR) Management** + +RTMR extension capabilities allow applications to record security-relevant events that become part of the attestation evidence. [6](#0-5) This functionality is essential for maintaining a verifiable chain of custody for application operations and ensuring that all security-relevant state changes are recorded in the hardware-protected measurement registers. + +**Cryptographic Key Derivation Services** + +The guest agent provides sophisticated key derivation services based on the application's cryptographic identity and attestation state. [7](#0-6) These services enable applications to derive unique cryptographic keys for specific purposes while maintaining verifiable links to the application's identity and the integrity of the execution environment. + +**TLS Certificate Management** + +Automated TLS certificate generation and management ensures secure communication channels for application services. [8](#0-7) The certificate authority integration allows for both standard TLS certificates and Remote Attestation TLS (RA-TLS) certificates that embed attestation evidence directly in the certificate chain, enabling clients to verify both the communication channel and the execution environment simultaneously. + +## **Container Lifecycle and Runtime Management** + +**Docker Integration and Container Operations** + +The guest agent maintains comprehensive integration with the container runtime environment, providing detailed visibility into container operations and lifecycle management. [9](#0-8) This integration enables real-time monitoring of application containers, including state tracking, resource utilization monitoring, and operational health assessment that supports both automated management and manual troubleshooting scenarios. + +**Application Composition Processing** + +Container deployment is managed through structured application composition files that define the complete application stack configuration. [10](#0-9) The guest agent processes these compositions to ensure proper container configuration, networking setup, and security policy enforcement while maintaining auditability of the deployment configuration through cryptographic hashing and attestation integration. + +**Log Management and Monitoring** + +Comprehensive logging capabilities provide detailed visibility into container operations while respecting privacy and security requirements. [11](#0-10) The logging system supports real-time streaming, historical log retrieval, and flexible filtering options that enable effective debugging and operational monitoring without compromising sensitive data or security boundaries. + +## **System Monitoring and Health Services** + +**Resource Monitoring and Metrics Collection** + +The guest agent implements detailed system monitoring capabilities that track CPU utilization, memory usage, disk space, and network activity across the guest environment. [12](#0-11) These metrics support both operational monitoring and capacity planning while providing essential data for automated scaling and resource management decisions. + +**Network Interface and Connectivity Management** + +Network monitoring capabilities provide comprehensive visibility into network configuration, traffic patterns, and connectivity status. [13](#0-12) The system tracks both standard network interfaces and specialized secure communication channels, ensuring that network connectivity issues can be quickly identified and resolved while maintaining security isolation requirements. + +**Watchdog and Health Check Services** + +Integrated watchdog functionality ensures system reliability and enables integration with systemd service management. [14](#0-13) The health check system continuously monitors service availability and can automatically trigger recovery procedures when anomalies are detected, ensuring high availability and reliable operation in production environments. + +## **Communication Interfaces and API Services** + +**RPC Service Architecture** + +The guest agent implements multiple RPC interfaces designed for different security contexts and operational requirements. [15](#0-14) These interfaces provide structured access to attestation services, cryptographic operations, and system management functions while maintaining appropriate security boundaries and access controls for different categories of clients and operations. + +**External HTTP Interface and Dashboard** + +A comprehensive web-based dashboard provides operational visibility and management capabilities for authorized users. [16](#0-15) The dashboard interface supports both human operators and automated tools, providing access to system status, container information, and operational metrics while respecting privacy and security configuration settings. + +**VSOCK Communication Channel** + +Secure host-guest communication is facilitated through VSOCK interfaces that provide isolation and security guarantees. [17](#0-16) This communication channel enables secure coordination between the host system and guest environment while maintaining the security boundaries essential for trusted execution environments. + +## **Operational Security and Governance** + +**Application Information and Identity Management** + +The guest agent maintains comprehensive application identity information that enables verification of application authenticity and operational context. [18](#0-17) This information includes application identifiers, instance information, device identification, and cryptographic evidence that supports both operational management and security verification requirements. + +**Configuration Security and Integrity** + +All configuration data is processed with integrity verification and security validation to ensure that only authorized and verified configurations can be deployed. [19](#0-18) The configuration system supports both development and production scenarios while maintaining strict security controls and auditability requirements that are essential for production deployment scenarios. + +The dstack guest agent represents a sophisticated and comprehensive solution for secure container orchestration within trusted execution environments. Its multi-layered architecture, comprehensive security services, and robust operational capabilities make it an essential component for organizations requiring verifiable and secure cloud computing solutions. For detailed implementation references and integration guidance, consult the [dstack guest agent source code](https://github.com/Dstack-TEE/dstack/tree/main/guest-agent) and associated documentation resources. + +**Notes** + +The guest agent serves as the cornerstone of dstack's security architecture, implementing Intel TDX attestation services, container lifecycle management, cryptographic key derivation, and comprehensive system monitoring within a unified service framework. Its role in maintaining security boundaries, enabling verifiable computation, and providing operational visibility makes it critical for the governance and security of the overall dstack system. Proper configuration and deployment of the guest agent is essential for achieving the security guarantees and operational reliability that dstack provides for confidential computing workloads. diff --git a/docs/concepts/core-kms.mdx b/docs/concepts/core-kms.mdx new file mode 100644 index 00000000..c6afea3c --- /dev/null +++ b/docs/concepts/core-kms.mdx @@ -0,0 +1,147 @@ +--- +title: "KMS Core" +description: "Comprehensive technical deep dive into dstack's Key Management Service - the critical security and governance layer" +--- + +## Configuration + +```toml +# kms.toml - Complete KMS Configuration +[default] +workers = 8 # Number of worker threads for async operations +max_blocking = 64 # Maximum blocking threads for I/O operations +ident = "DStack KMS" # Service identifier for logging and metrics +temp_dir = "/tmp" # Temporary directory for operations +keep_alive = 10 # HTTP keep-alive timeout in seconds +log_level = "info" # Logging level (debug, info, warn, error) + +[rpc] +address = "0.0.0.0" # RPC server bind address +port = 8000 # RPC server port + +[rpc.tls] +key = "/etc/kms/certs/rpc.key" # TLS private key for RPC server +certs = "/etc/kms/certs/rpc.crt" # TLS certificate for RPC server + +[rpc.tls.mutual] +ca_certs = "/etc/kms/certs/tmp-ca.crt" # CA certificates for mutual TLS +mandatory = false # Whether mutual TLS is required + +[core] +cert_dir = "/etc/kms/certs" # Directory containing all certificates and keys +subject_postfix = ".dstack" # Subject postfix for generated certificates +admin_token_hash = "" # SHA256 hash of admin token for privileged operations + +[core.image] +verify = true # Enable OS image verification against trusted measurements +cache_dir = "/usr/share/dstack/images" # Directory for caching downloaded OS images +download_url = "http://localhost:8000/{OS_IMAGE_HASH}.tar.gz" # Template URL for image downloads +download_timeout = "2m" # Timeout for image download operations + +[core.auth_api] +type = "webhook" # Authorization API type (webhook or dev) + +[core.auth_api.webhook] +url = "http://auth-api:8000" # Webhook URL for authorization decisions + +[core.auth_api.dev] +gateway_app_id = "any" # Development mode: allow any gateway app ID + +[core.onboard] +enabled = true # Enable onboarding service for new KMS instances +auto_bootstrap_domain = "" # Domain for automatic bootstrapping (empty = manual) +quote_enabled = true # Enable TDX quote verification during onboarding +address = "0.0.0.0" # Onboarding service bind address +``` + +## dstack KMS: The Critical Security Foundation + +**dstack KMS serves as the cornerstone of the entire trusted computing infrastructure**, providing enterprise-grade cryptographic services with blockchain integration and comprehensive attestation capabilities. The KMS operates as the primary trust anchor, responsible for key derivation, certificate authority functions, and application authorization within the Trusted Execution Environment ecosystem. + +### KMS Architecture and Core Components + +**The KMS implementation consists of three primary architectural components** that work in concert to provide comprehensive key management and security services [1](#0-0) . + +**The main dstack-kms service** functions as the central RPC service handling all application key requests, quote verification, and boot information validation. This service maintains the core cryptographic operations and interfaces directly with requesting applications through a secure RPC protocol [2](#0-1) . + +**The dstack-kms-auth-eth component** provides blockchain integration for permission validation through a sophisticated two-step verification process. This component first validates against the KMS control contract, then performs application-specific authorization checks through dedicated app control contracts [3](#0-2) . + +**Authorization contracts deployed on Ethereum-compatible chains** maintain the complete registry of authorized applications, allowed KMS instance measurements, permitted OS images, and registered KMS root keys. These contracts provide immutable governance and audit trails for all authorization decisions [4](#0-3) . + +### KMS Boot Modes and Trust Models + +**The KMS supports three distinct operational modes**, each providing different levels of security, persistence, and upgrade capabilities to accommodate various deployment scenarios and trust requirements. + +**Non-KMS Mode** operates as a stateless configuration generating ephemeral application keys during startup with no persistent disk state. This mode enforces strict application identity validation where the app-id must exactly equal the compose-hash, ensuring complete deterministic behavior. The key provider is recorded in RTMR as `{"type": "none", "id": ""}` indicating no external key provider dependency [5](#0-4) . + +**Local-Key-Provider Mode** utilizes SGX sealing mechanisms through the gramine-sealing-key-provider for persistent key storage while maintaining strict measurement validation. This mode supports stateful operations with persistent disk storage but prohibits application upgrades, ensuring consistent cryptographic identity. The key provider information is recorded as `{"type": "local-sgx", "id": ""}` in RTMR for verification purposes [6](#0-5) . + +**KMS Mode** enables the most flexible deployment scenario supporting application upgrades and sophisticated application identity management through blockchain-based authorization. This mode derives app-id from the deployer's Ethereum address combined with a salt value, providing upgradeable application identity while maintaining security. The key provider is recorded as `{"type": "kms", "id": ""}` establishing the KMS root public key as the trust anchor [7](#0-6) . + +### KMS Service Initialization and Bootstrap Process + +**The KMS initialization process follows a sophisticated multi-stage bootstrap procedure** ensuring secure establishment of cryptographic trust anchors and proper service configuration [8](#0-7) . + +**During the onboarding phase**, the KMS determines whether to bootstrap a new instance or join an existing KMS cluster through key replication. The onboarding service provides a web interface for manual configuration or can perform automatic bootstrapping when configured with a domain parameter [9](#0-8) . + +**Bootstrap operations generate two critical root keys**: a CA root key used for issuing X.509 certificates enabling HTTPS traffic for applications, and a K256 root key used for deriving Ethereum-compatible signing keys for blockchain interactions. These root keys establish the cryptographic foundation for all subsequent key derivation operations [10](#0-9) . + +**The KMS service startup sequence** includes certificate updates, RPC method registration, and state initialization with comprehensive error handling and logging throughout the process [11](#0-10) . + +### Key Derivation and Cryptographic Operations + +**The KMS implements sophisticated key derivation functions** providing multiple cryptographic keys for different application purposes while maintaining cryptographic isolation between applications and use cases [12](#0-11) . + +**Application disk encryption keys** are derived using key derivation functions combining the root CA key with application ID, instance ID, and a specific context identifier for disk encryption purposes. This ensures each application instance receives unique encryption keys that cannot be accessed by other applications [13](#0-12) . + +**Environment variable encryption keys** utilize X25519 key agreement protocols derived from the root CA key and application ID, providing secure encryption for sensitive configuration data that can only be decrypted within the target application's TEE [14](#0-13) . + +**Ethereum-compatible signing keys** are generated using K256 elliptic curve cryptography with proper signature validation to ensure cryptographic integrity and blockchain compatibility for applications requiring smart contract interactions [15](#0-14) . + +### Attestation and Quote Verification + +**The KMS performs comprehensive TDX quote validation** for all requesting applications, extracting and validating measurement registers, application information, and device identity before authorizing key provisioning [16](#0-15) . + +**OS image verification** ensures applications are running trusted operating system images by downloading, extracting, and validating image checksums against known-good measurements. The KMS maintains a local cache of verified images and their corresponding measurement registers to optimize subsequent validation operations [17](#0-16) . + +**The attestation process** includes validation of MRTD (Measurement of Root of Trust for Detection), RTMR registers containing boot measurements, application configuration, and runtime state to ensure complete system integrity before key provisioning [18](#0-17) . + +### KMS Replication and High Availability + +**KMS replication enables horizontal scaling** and high availability through secure key transfer between authenticated KMS instances. The replication process utilizes RA-TLS (Remote Attestation with Transport Layer Security) to establish secure channels between KMS nodes [19](#0-18) . + +**The replication workflow** requires pre-registration of target KMS measurements in the KmsAuth contract, followed by secure key transfer from the source instance after comprehensive quote validation and blockchain authorization verification. + +**Post-replication operation** results in multiple KMS instances sharing identical root keys, enabling load distribution and fault tolerance while maintaining cryptographic consistency across the distributed system. + +### RPC Service Interface and API Operations + +**The KMS exposes a comprehensive RPC API** supporting key provisioning, certificate signing, metadata retrieval, and administrative operations through a secure protocol buffer interface [20](#0-19) . + +**GetAppKey operations** handle the core key provisioning workflow, validating TDX quotes, checking blockchain authorization, and returning the complete set of application keys including disk encryption, environment encryption, and signing keys [21](#0-20) [22](#0-21) . + +**Certificate signing services** enable applications to obtain signed TLS certificates through Certificate Signing Request validation, quote verification, and hierarchical certificate authority operations [23](#0-22) [24](#0-23) . + +**Metadata and health check endpoints** provide KMS instance information, bootstrap status, and configuration details necessary for monitoring and integration with external services [25](#0-24) . + +### Security Architecture and Trust Anchors + +**The KMS establishes a complete chain of trust** from hardware-based attestation through blockchain governance to application-level cryptographic operations. This multi-layered security architecture ensures comprehensive protection against various attack vectors and unauthorized access attempts. + +**Root key protection** utilizes TEE-based isolation combined with encrypted local storage and distributed replication to prevent single points of failure while maintaining cryptographic security across the distributed system. + +**Authorization decisions** integrate blockchain-based smart contracts with real-time attestation validation, ensuring both immutable governance policies and dynamic security assessment for every key provisioning request. + +**The KMS serves as the fundamental security primitive** for the entire dstack ecosystem, providing the cryptographic foundation upon which all other security mechanisms depend. + +## Reference Links + +- [dstack KMS Source Code](https://github.com/Dstack-TEE/dstack/tree/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms) +- [KMS RPC Protocol Definition](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/rpc/proto/kms_rpc.proto) +- [KMS Main Service Implementation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs) +- [KMS Configuration System](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/config.rs) + +## Notes + +The dstack KMS represents a sophisticated approach to enterprise key management within Trusted Execution Environments, combining hardware-based attestation, blockchain governance, and comprehensive cryptographic services. Its role as the primary trust anchor makes proper configuration and deployment critical for overall system security. The three-tier boot mode architecture provides flexibility for different deployment scenarios while maintaining strong security guarantees appropriate for each use case. + diff --git a/docs/concepts/core-os.mdx b/docs/concepts/core-os.mdx new file mode 100644 index 00000000..7aa26ed5 --- /dev/null +++ b/docs/concepts/core-os.mdx @@ -0,0 +1,190 @@ +--- +title: "DStack-OS Core" +description: "Deep dive into dstack's operating system core components, guest agent architecture, and secure boot implementation" +--- + +# dstack OS Core Implementation + +The dstack operating system provides a secure, minimal foundation built on TDX (Trust Domain Extensions) with comprehensive attestation and full disk encryption capabilities. At its core lies the **dstack-guest-agent**, a critical runtime service that manages all TEE operations, cryptographic functions, and container orchestration within Confidential Virtual Machines. + +## Guest Agent Configuration + +```toml +# dstack Guest Agent Configuration +# Core service configuration for TEE operations and container management + +[default] +workers = 8 # Tokio runtime worker threads +max_blocking = 64 # Maximum blocking task threads +ident = "Dstack guest agent" # Service identification +temp_dir = "/tmp" # Temporary file storage +keep_alive = 10 # Connection keep-alive timeout +log_level = "debug" # Logging verbosity level + +[default.core] +keys_file = "/dstack/.host-shared/.appkeys.json" # Application cryptographic keys +compose_file = "/dstack/.host-shared/app-compose.json" # Container deployment configuration +sys_config_file = "/dstack/.host-shared/.sys-config.json" # System configuration parameters +data_disks = ["/"] # Persistent storage mount points + +[default.core.simulator] +enabled = false # TDX simulation mode for development +quote_file = "quote.hex" # Simulated TDX quote file +event_log_file = "eventlog.json" # Simulated event log file + +# Internal RPC Interface (Legacy v0 - Tappd compatibility) +[internal-v0] +address = "unix:/var/run/tappd.sock" # Unix domain socket for legacy applications +reuse = true # Socket reuse configuration + +# Internal RPC Interface (Current) +[internal] +address = "unix:/var/run/dstack.sock" # Unix domain socket for container applications +reuse = true # Socket reuse configuration + +# External HTTP Interface +[external] +address = "0.0.0.0" # HTTP server bind address +port = 8090 # HTTP server port for dashboard and management + +# Guest API Interface +[guest-api] +address = "vsock:0xffffffff" # VSOCK communication with host VMM +``` + +## dstack Guest Agent Architecture + +**Runtime Service Foundation** + +The dstack guest agent represents the cornerstone of the dstack OS architecture, functioning as a multi-service runtime daemon that orchestrates all confidential computing operations within TDX-enabled virtual machines. [1](#0-0) + +**Concurrent Service Architecture** + +The guest agent implements a sophisticated concurrent service model using Tokio's asynchronous runtime, operating four distinct service interfaces simultaneously. Each service is designed for specific communication patterns and security contexts within the confidential computing environment. [2](#0-1) + +**Internal RPC Services** + +The system maintains two internal RPC interfaces for container communication. The legacy v0 interface provides backward compatibility with existing Tappd applications, while the current internal interface offers enhanced functionality for modern container workloads. Both interfaces utilize Unix domain sockets with proper permission management to allow any user within the CVM to access cryptographic services. [3](#0-2) + +**External HTTP Interface** + +The external HTTP interface serves as the primary management and monitoring endpoint, providing both RESTful APIs and web dashboard functionality. This interface includes comprehensive health monitoring integration with systemd watchdog services, ensuring robust service availability and automatic recovery mechanisms. [4](#0-3) + +**VSOCK Guest API** + +The VSOCK-based Guest API establishes secure communication channels between the guest agent and the host Virtual Machine Manager (VMM). This interface enables privileged operations such as system configuration, attestation coordination, and secure key provisioning without requiring network-based communication. [5](#0-4) + +## Cryptographic Operations and Key Management + +**Application State Management** + +The guest agent maintains comprehensive application state through the AppState structure, which encapsulates all cryptographic materials, system configurations, and certificate management components. This centralized state management ensures consistent access to security primitives across all service interfaces. [6](#0-5) + +**TLS Certificate Generation** + +The system implements dynamic TLS certificate generation using Remote Attestation TLS (RA-TLS) protocols. Each certificate request includes comprehensive TDX attestation data, enabling verifiable proof of the certificate's origin from within a genuine TDX environment. The certificate generation process supports both server and client authentication modes with flexible subject alternative name configuration. [7](#0-6) + +**Cryptographic Key Derivation** + +Application-specific key derivation follows a hierarchical deterministic approach using ECDSA P-256 curves. The system derives unique keys for specific purposes while maintaining cryptographic proof chains that validate key authenticity through signature verification against root application keys. [8](#0-7) + +**TDX Quote Generation and Attestation** + +The guest agent provides comprehensive TDX quote generation capabilities, supporting both raw quote requests and structured attestation protocols. The system includes event log integration for maintaining cryptographic measurement chains and supports simulation modes for development environments. [9](#0-8) + +## System Initialization and Boot Process + +**Boot Preparation Phase** + +The dstack OS initialization begins with the dstack-prepare.sh script, which establishes the foundational runtime environment. This script creates overlay filesystems for critical system directories, ensuring that modifications to sensitive areas like /etc/wireguard, /etc/docker, and /usr/bin are contained within volatile storage. [10](#0-9) + +**TDX Module Loading and Time Synchronization** + +The preparation phase includes loading the TDX guest kernel module and establishing synchronized system time through chrony. Time synchronization is critical for certificate validity and attestation timestamp accuracy in the confidential computing environment. [11](#0-10) + +**System Setup Orchestration** + +Following preparation, the dstack-util setup command orchestrates the complete system configuration process. This includes cryptographic key provisioning, full disk encryption establishment, environment variable decryption, and network security configuration. [12](#0-11) + +**RTMR Measurement Chain** + +The system maintains a comprehensive measurement chain using TDX RTMR3 (Runtime Measurement Register), recording critical system events including system preparation markers, application identifiers, compose file hashes, and instance identifiers. This measurement chain provides cryptographic proof of system integrity and configuration. [13](#0-12) + +## Full Disk Encryption and Storage Management + +**LUKS2 Encryption Implementation** + +The dstack OS implements full disk encryption using LUKS2 with AES-XTS-Plain64 cipher configuration and PBKDF2 key derivation. The encryption setup process includes automatic key provisioning from either KMS services or local sealing mechanisms, ensuring data protection without manual intervention. [14](#0-13) + +**ZFS Filesystem Integration** + +The encrypted storage utilizes ZFS with Blake3 checksums for enhanced data integrity and automatic pool expansion capabilities. The ZFS configuration includes persistent mounting and optimized settings for confidential computing workloads, including disabled access time tracking and optimized compression. [15](#0-14) + +**Key Management Integration** + +The system supports multiple key provisioning modes including KMS integration for cloud deployments, local SGX sealing for edge computing, and development mode for testing environments. Each mode provides appropriate security guarantees while maintaining operational flexibility. [16](#0-15) + +## Container Deployment and Orchestration + +**Application Composition Framework** + +Container deployment follows a structured application composition framework defined in JSON configuration files. The system supports multiple runner types including Docker Compose for complex multi-container applications and bash scripts for custom deployment scenarios. [17](#0-16) + +**Container Lifecycle Management** + +The deployment process includes comprehensive lifecycle management with orphan container removal, Docker daemon restart coordination, and systematic cleanup of unused images and volumes. This ensures clean deployment states and optimal resource utilization within the constrained CVM environment. [18](#0-17) + +**Pre-launch Script Execution** + +The system supports pre-launch script execution for custom environment preparation, enabling applications to perform initialization tasks before container startup. This capability supports complex deployment scenarios while maintaining security isolation. [19](#0-18) + +## Network Security and Gateway Integration + +**WireGuard VPN Configuration** + +Network security relies on WireGuard VPN configuration with dynamic peer management and iptables-based access control. The system automatically generates cryptographic key pairs and establishes secure tunnels to dstack-gateway instances for external connectivity. [20](#0-19) + +**Certificate-based Gateway Authentication** + +Gateway registration employs certificate-based authentication using RA-TLS certificates that include TDX attestation data. This ensures that only genuine TDX environments can establish gateway connections while providing cryptographic proof of the guest's security posture. [21](#0-20) + +## Environment Variable Management + +**Encrypted Environment Processing** + +The system implements secure environment variable management through encrypted storage and runtime decryption. Environment variables are encrypted using AES keys derived from the application's cryptographic material and decrypted only during system initialization within the secure TDX environment. [22](#0-21) + +**Access Control and Validation** + +Environment variable access is controlled through allowlist mechanisms defined in the application composition configuration. This prevents unauthorized access to sensitive configuration data while enabling necessary application functionality. [23](#0-22) + +## Health Monitoring and System Integration + +**Systemd Watchdog Integration** + +The guest agent integrates comprehensively with systemd watchdog services, providing continuous health monitoring and automatic service recovery. The watchdog implementation includes HTTP-based health checks and proper notification protocols to ensure system reliability. [4](#0-3) + +**Application Information Reporting** + +The system provides detailed application information reporting including TDX measurements, cryptographic signatures, and system configuration data. This information enables external verification of the system's security posture and operational status. [24](#0-23) + +## Notes + +The dstack OS represents a comprehensive confidential computing platform that prioritizes **security-first architecture** through TDX attestation integration, **minimal attack surface** via targeted component selection, and **enterprise-grade reliability** through robust monitoring and recovery mechanisms. The guest agent serves as the central orchestration point for all confidential computing operations, providing a secure foundation for deploying sensitive applications while maintaining familiar Docker-based workflows for developers. + +The architecture emphasizes **cryptographic verifiability** at every layer, from boot-time measurements through runtime certificate generation, ensuring that all system operations can be cryptographically verified by external parties. This approach enables **zero-trust deployment models** where applications can verify their execution environment before processing sensitive data. + +### Reference Links + +- [dstack Guest Agent Implementation](https://github.com/Dstack-TEE/dstack/tree/main/guest-agent) - Complete guest agent source code and documentation +- [System Setup Utilities](https://github.com/Dstack-TEE/dstack/tree/main/dstack-util) - System initialization and configuration management +- [Boot Process Scripts](https://github.com/Dstack-TEE/dstack/tree/main/basefiles) - System preparation and container deployment scripts +- [TDX Attestation Integration](https://github.com/Dstack-TEE/dstack/tree/main/tdx-attest) - TDX-specific attestation and measurement utilities + +### Continue Learning + +- [Core Components Overview](/docs/concepts/core-components) - Review the complete architecture +- [Security Model](/docs/concepts/security-model) - Deep dive into security architecture +- [Architecture](/docs/concepts/architecture) - Understand the complete system design +- [Getting Started](/docs/getting-started/start) - Begin deploying applications + diff --git a/docs/concepts/core-tdxctl.mdx b/docs/concepts/core-tdxctl.mdx new file mode 100644 index 00000000..1e21d6af --- /dev/null +++ b/docs/concepts/core-tdxctl.mdx @@ -0,0 +1,306 @@ +--- +title: "DStack-Util Core" +description: "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](#0-0) + +## 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](#0-1) +- **System Setup Module**: Comprehensive system initialization with full disk encryption [3](#0-2) +- **Cryptographic Services**: X25519 Diffie-Hellman key agreement and AES-GCM encryption/decryption [4](#0-3) +- **TDX Attestation**: Integration with tdx-attest library for low-level TDX functionality [5](#0-4) + +## Commands Reference + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandPurposeParameters
ReportGet TDX report from stdin report dataNone (reads from stdin)
QuoteGenerate TDX quote from stdin report dataNone (reads from stdin)
ExtendExtend Runtime Measurement Register (RTMR)--event, --payload
ShowDisplay current RTMR state and measurementsNone
SetupComplete system preparation with FDE--work-dir, --device, --mount-point
GenRaCertGenerate Remote Attestation certificate--ca-cert, --ca-key, --cert-path, --key-path
GenCaCertGenerate Certificate Authority certificate--cert, --key, --ca-level
GenAppKeysGenerate application keys--ca-level, --output
HexHex encode data from file or stdinfilename (optional)
RandGenerate random data--bytes, --output, --hex
NotifyHostSend notifications to host system--url, --event, --payload
RemoveOrphansClean up orphaned Docker containers--compose
+ +**[6](#0-5)** + +## 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](#0-6) +- **TDX Quote Generation**: Produces signed quotes for remote attestation [8](#0-7) +- **RTMR Extension Operations**: Extends Runtime Measurement Registers with application events [9](#0-8) +- **Measurement Display**: Shows current RTMR state and decoded measurement information [10](#0-9) + +### 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](#0-10) +- **ZFS Integration**: Creates encrypted ZFS pools with Blake3 checksums and autoexpand capabilities [12](#0-11) +- **Mount Management**: Handles both new initialization and existing disk mounting [13](#0-12) + +#### Key Management Integration +- **KMS-based Key Retrieval**: Supports remote key management services with attestation [14](#0-13) +- **Local Key Provider**: SGX-based key derivation for isolated environments [15](#0-14) +- **Key Provider Verification**: Validates and measures key providers for security [16](#0-15) + +### 3. Cryptographic Services + +Advanced cryptographic operations including: + +- **Certificate Generation**: Creates Remote Attestation TLS certificates with TDX quotes [17](#0-16) +- **CA Certificate Creation**: Generates Certificate Authority certificates with attestation [18](#0-17) +- **Application Key Management**: Produces complete application key sets with quotes [19](#0-18) +- **X25519 Operations**: X25519 key agreement and AES-GCM decryption [4](#0-3) + +### 4. Container Management + +Docker integration and container lifecycle management: + +- **Orphaned Container Cleanup**: Identifies and removes containers from outdated compose configurations [20](#0-19) +- **Docker Registry Setup**: Configures mirror registries and authentication [21](#0-20) +- **Account Configuration**: Handles Docker login with encrypted tokens [22](#0-21) + +## Usage Examples + +### TDX Operations +```bash +# 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 +```bash +# Complete system setup with encrypted disk +dstack-util setup \ + --work-dir /dstack \ + --device /dev/vda2 \ + --mount-point /dstack/data +``` + +### Certificate Generation +```bash +# 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 +```bash +# 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](#0-22) +- **Key Provider Verification**: Measures and validates key provider information [24](#0-23) +- **Boot Process Measurement**: Tracks system initialization stages through RTMR extensions [25](#0-24) + +### 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](#0-25) +- **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](#0-26) +- **Certificate-based Authentication**: Uses Remote Attestation TLS for gateway registration [28](#0-27) +- **Firewall Configuration**: Sets up iptables rules for secure WireGuard operation [29](#0-28) + +### Host Communication + +Provides secure bidirectional communication with the host system: + +- **Event Notification**: Sends structured events and payloads to host API [30](#0-29) +- **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](#0-30) +3. **Measure App Composition**: The application composition (such as configuration and compose files) is measured and logged for attestation. [23](#0-22) +4. **Request App Keys**: The system requests application keys from the configured key provider. [32](#0-31) +5. **Setup Disk Encryption**: Full disk encryption is set up using the provided or derived keys. [13](#0-12) +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](#0-26) +8. **Setup Docker**: The Docker runtime is initialized and prepared for container workloads. [33](#0-32) +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](#0-31) + +B. **Provider Type**: + - If **KMS**: [34](#0-33) + C. Connect to the Key Management Service (KMS). + D. Validate the KMS certificate. + E. Decrypt application keys received from KMS. + - If **Local**: [15](#0-14) + F. Retrieve the local sealing key. + G. Derive the key from SGX hardware. + H. Decrypt application keys using the derived key. + - If **None**: [35](#0-34) + 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](#0-15) + +L. **Measure Provider**: Finally, the provider's information is measured and logged for attestation. [24](#0-23) + +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](#0-4) +- **ra-tls**: Remote Attestation TLS certificate generation [36](#0-35) +- **dstack-kms-rpc**: Key Management Service communication [37](#0-36) +- **dstack-gateway-rpc**: Gateway registration and WireGuard setup [38](#0-37) +- **host-api**: Host system communication and event reporting [39](#0-38) + +## 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 + + + +### Related Topics +- [Security Model](/docs/concepts/security-model) - Learn about TDX attestation and measurement +- [Architecture](/docs/concepts/architecture) - Understand TDX integration in the system +- [Key Management](/docs/concepts/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](#0-39) and application runtime [41](#0-40) 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. diff --git a/docs/concepts/core-vmm.mdx b/docs/concepts/core-vmm.mdx new file mode 100644 index 00000000..2be831fb --- /dev/null +++ b/docs/concepts/core-vmm.mdx @@ -0,0 +1,137 @@ +--- +title: "VMM Core" +description: "details the configuration, interfaces, and orchestration role of the dstack virtual machine manager (VMM), including its integration with gateway services and secure workload management." +--- + +# dstack-vmm + +The VMM provides orchestration capabilities through several service interfaces: + +| **Service** | **Endpoint** | **Purpose** | +|-------------|-------------|-------------| +| RPC API | `/prpc` | VM lifecycle management and operations | +| Host API | `/api` | CVM notifications and host information | +| Guest API | `/guest` | Proxied access to CVM guest agents | +| Web UI | `/` | HTML console for browser-based management | + + ## vmm Configuration + [See full VMM configuration reference](https://deepwiki.com/Dstack-TEE/dstack/2.1-dstack-vmm) + + + +```toml +# vmm.toml - Configuration for Dstack VMM + +# --------- General VMM Parameters --------- +workers = 8 # Number of worker threads for task execution +max_blocking = 64 # Maximum number of blocking tasks allowed +ident = "Dstack VMM" # Identifier/name for the VMM instance +temp_dir = "/tmp" # Directory for temporary files (e.g., sockets, images) +keep_alive = 10 # Time (in seconds) to keep idle resources alive +log_level = "info" # Logging verbosity: trace, debug, info, warn, error +address = "unix:./vmm.sock" # Unix socket address for VMM communication +reuse = true # Reuse the socket if already exists (avoids conflicts) +kms_url = "http://127.0.0.1:8081" # URL for Key Management Service (KMS) +image_path = "/var/lib/dstack/images" # Directory to store VM/container images +run_path = "/var/lib/dstack/vms" # Directory to store running VM state and files + +# --------- Networking Configuration --------- +[networking] +mode = "user" # Networking mode: user, bridge, host, etc. +net = "10.0.2.0/24" # Subnet for VMs/containers +dhcp_start = "10.0.2.10" # Starting IP for DHCP-assigned addresses +restrict = false # Restrict networking for isolation (false = open) + +# --------- CVM (Compute Virtual Machine) Parameters --------- +[cvm] +qemu_path = "/usr/bin/qemu-system-x86_64" # Path to QEMU executable +kms_urls = ["http://127.0.0.1:8081"] # List of Key Management Service URLs +gateway_urls = ["http://127.0.0.1:8082"] # URLs for gateway agents/services +pccs_url = "" # Optional: SGX PCS URL (empty if unused) +docker_registry = "" # Optional: Docker registry for images +max_disk_size = 500 # Maximum disk size per VM (GB) +cid_start = 1000 # Starting CID (Container ID) for VMs +cid_pool_size = 1000 # Number of CIDs available for allocation +max_allocable_vcpu = 20 # Maximum virtual CPUs allocable per VM +max_allocable_memory_in_mb = 100000 # Maximum RAM per VM (MB) +qmp_socket = false # Enable QEMU Machine Protocol socket (for advanced control) +user = "" # Run VMs as this user (empty = default) +use_mrconfigid = true # Use measured config ID for attestation + +# ----- Port Mapping for CVM ----- +[cvm.port_mapping] +enabled = false # Enable port mapping between host and guest +address = "127.0.0.1" # Host address for mapped ports +range = [ + { protocol = "tcp", from = 1, to = 20000 }, # Range of TCP ports available for mapping +] + +# ----- Auto-Restart for CVM ----- +[cvm.auto_restart] +enabled = true # Automatically restart VMs on failure +interval = 20 # Interval (seconds) before attempting restart + +# ----- GPU Passthrough for CVM ----- +[cvm.gpu] +enabled = false # Enable GPU passthrough to VMs +listing = ["10de:2335"] # List of allowed GPU devices (PCI IDs) +exclude = [] # List of GPUs to exclude from passthrough +include = [] # List of GPUs to include (overrides 'listing') + +# --------- Gateway Service Configuration --------- +[gateway] +base_domain = "localhost" # Base domain for gateway routing +port = 8082 # Port for gateway HTTP interface +agent_port = 8090 # Port for gateway agent communication + +# --------- Authentication and Tokens --------- +[auth] +enabled = false # Enable authentication for API/services +tokens = [] # List of valid API tokens (empty = no auth) + +# --------- Supervisor Process Configuration --------- +[supervisor] +exe = "./supervisor" # Path to supervisor executable +sock = "./run/supervisor.sock" # Path to supervisor socket file +pid_file = "./run/supervisor.pid" # Path to supervisor PID file +log_file = "./run/supervisor.log" # Path to supervisor log file +detached = false # Run supervisor in background (daemon) +auto_start = true # Start supervisor automatically with VMM + +# --------- Host API Endpoint --------- +[host_api] +ident = "Dstack VMM" # Identifier for the Host API instance +address = "vsock:2" # Address (VSOCK) for host API communication +port = 10000 # Port for host API + +# --------- Key Provider Configuration --------- +[key_provider] +enabled = true # Enable external key provider +address = "127.0.0.1" # Address of the key provider service +``` + + +--- + +## Gateway Integration with the VMM + +The integration of the gateway within the VMM's configuration reflects the tightly coupled nature of secure, orchestrated deployments in dstack. By defining gateway parameters—such as the base domain, network ports, and agent interface—directly alongside VM and cluster settings, dstack ensures that network exposure, TLS policy, and VPN tunneling are always synchronized with the lifecycle of each Confidential VM. The VMM is responsible not only for creating and maintaining the compute environment, but also for provisioning and updating the gateway, allowing seamless coordination between workload orchestration and secure service exposure. This architecture eliminates configuration drift and centralizes operational control, so that every application endpoint published by the gateway is cryptographically tied to the trusted state managed by the VMM. + +## Next Steps + +Now that you understand VMM orchestration, continue learning about dstack's core components: + + + +### Related Topics +- [Networking](/docs/concepts/networking) - Learn about dstack's network architecture +- [Architecture](/docs/concepts/architecture) - Understand the overall system design + + diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx new file mode 100644 index 00000000..4d860360 --- /dev/null +++ b/docs/concepts/networking.mdx @@ -0,0 +1,500 @@ +--- +title: "Networking Architecture" +description: "dstack implements a sophisticated networking model to ensure secure, isolated, and high-performance communication between all components. This page walks you through how networking works in dstack, from routing external HTTPS traffic to managing secure connections inside confidential VMs." +--- + +The dstack networking architecture is built on multiple layers, each designed to deliver **security**, **isolation**, and **flexibility** for your deployments. By understanding how these layers interact, you'll be better equipped to optimize performance, maintain strong security boundaries, and quickly resolve any networking issues that arise. + +## Network Model Overview + +```mermaid +graph TB + subgraph "Public Internet" + USER[Users/Clients] + DNS[DNS Servers] + end + + subgraph "Edge Layer" + LB[Load Balancer] + GW[dstack-gateway] + end + + subgraph "Management Network" + VMM[dstack-vmm] + API[Management APIs] + end + + subgraph "Secure Network" + WG[WireGuard Tunnels] + KMS[KMS in CVM] + end + + subgraph "Isolated CVMs" + CVM1[App CVM 1] + CVM2[App CVM 2] + CVM3[App CVM 3] + end + + USER -->|HTTPS| LB + USER -->|DNS Query| DNS + LB -->|HTTPS| GW + GW -->|WireGuard| CVM1 + GW -->|WireGuard| CVM2 + GW -->|WireGuard| CVM3 + VMM -->|Control| CVM1 + VMM -->|Control| CVM2 + VMM -->|Control| CVM3 + CVM1 -->|RA-TLS| KMS + CVM2 -->|RA-TLS| KMS + CVM3 -->|RA-TLS| KMS +``` + +## Network Layers (at a glance) + +
+ + {/* 1. Public Access */} +
+
+
+ 1 +
+ Public Access +
+
+ users connect to your app over HTTPS
+ DNS points to your app domain
+ (optional) CDN for static files +
+
HTTP/HTTPS, DNS
+
+ + {/* 2. Gateway Security */} +
+
+
+ 2 +
+ Gateway Security +
+
+ gateway handles TLS (auto certificates)
+ blocks attacks (WAF, rate limiting, DDoS protection)
+ supports HTTP/2 and HTTP/3 +
+
+ + {/* 3. Private VPN to CVMs */} +
+
+
+ 3 +
+ Private VPN to CVMs +
+
+ gateway connects to each Confidential VM (CVM) using a secure WireGuard tunnel. this keeps app traffic private and isolated. +
+
+ Show WireGuard config example +
+
+
Gateway
+ 
{`[Interface]
+Address = 10.9.0.1/24
+ListenPort = 51820
+PrivateKey = 
+
+[Peer]
+PublicKey = 
+AllowedIPs = 10.9.0.2/32`}
+
+
+
CVM
+ 
{`[Interface]
+Address = 10.9.0.2/24
+PrivateKey = 
+
+[Peer]
+PublicKey = 
+Endpoint = gateway.ip:51820
+AllowedIPs = 10.9.0.1/32`}
+
+
+
+
+ +
+ +### 4. Internal CVM Network + +Container-to-container communication within a CVM: + +```yaml +# Docker network configuration +networks: + internal: + driver: bridge + ipam: + config: + - subnet: 172.20.0.0/16 + internal: true # No external access + +services: + web: + networks: + - internal + - external + database: + networks: + - internal # Only internal access +``` + +## Traffic Routing + +### Domain-Based Routing + +dstack supports multiple routing patterns: + +
+

Routing Patterns:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PatternExampleUse Case
app.srv.domainmyapp.app.example.comDefault app routing
custom.domainapi.mycompany.comCustom domain via DNS TXT
port-N.srv.domain8080.app.example.comDirect port access
cvm-id.internalcvm-abc123.internalInternal debugging
+
+
+ +### Custom Domain Setup + +To use a custom domain, configure DNS records as follows: + +
+

DNS Configuration:

+ 
{`# DNS TXT record
+_dstack-app-address.api.mycompany.com TXT "app-id=abc123def456"
+
+# CNAME record
+api.mycompany.com CNAME gateway.example.com`}
+
+ +### Request Routing Flow + +```mermaid +graph TD + A[HTTPS Request] --> B{Parse Host Header} + B --> C{Custom Domain?} + C -->|Yes| D[DNS TXT Lookup] + C -->|No| E{Default Domain?} + D --> F[Get App ID] + E -->|Yes| G[Extract App ID] + E -->|No| H[404 Not Found] + F --> I[Route to CVM] + G --> I + I --> J[WireGuard Tunnel] + J --> K[Application] +``` + +--- + +## Network Security Framework + +### Port Security Configuration + +
+

Default Port Configuration:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PortServiceAccessSecurity
80HTTPPublicRedirect to HTTPS
443HTTPSPublicTLS 1.2+ only
51820WireGuardPublicKey-based auth
9080VMM APIInternalLocalhost only
8000KMS RPCInternalRA-TLS required
+
+
+ +### Firewall Configuration + +
+

Recommended Firewall Rules:

+ 
{`# Public interface - minimal exposure
+iptables -A INPUT -p tcp --dport 80 -j ACCEPT
+iptables -A INPUT -p tcp --dport 443 -j ACCEPT
+iptables -A INPUT -p udp --dport 51820 -j ACCEPT
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A INPUT -i lo -j ACCEPT
+iptables -P INPUT DROP
+
+# Internal interface - management traffic
+iptables -A INPUT -i eth1 -s 10.0.0.0/8 -p tcp --dport 9080 -j ACCEPT
+iptables -A INPUT -i eth1 -s 10.0.0.0/8 -p tcp --dport 8000 -j ACCEPT`}
+
+ +### Network Isolation Mechanisms + +
+

Multi-Layer Isolation:

+
+
+
+ + VLAN Separation: Different VLANs for management and application traffic +
+
+ + Network Namespaces: Each CVM has isolated network stack +
+
+ + Bridge Isolation: Separate bridges prevent cross-CVM communication +
+
+
+
+ + Firewall Rules: Default deny with explicit allow rules +
+
+ + WireGuard Encryption: All CVM traffic encrypted +
+
+
+
+ +--- + +## HTTPS & Certificate Management + +### Automatic Certificate Provisioning + +dstack automatically provisions and renews TLS certificates using Let's Encrypt: + +```mermaid +sequenceDiagram + participant App + participant Gateway + participant LE as Let's Encrypt + participant DNS + + App->>Gateway: Request certificate + Gateway->>DNS: Create TXT record + Gateway->>LE: Request certificate + LE->>DNS: Verify challenge + DNS->>LE: Challenge response + LE->>Gateway: Issue certificate + Gateway->>App: Certificate ready + + Note over Gateway: Auto-renewal 30 days before expiry +``` + +### Certificate Configuration + +
+

Gateway Certificate Settings:

+ 
{`# gateway.toml certificate settings
+[certificate]
+# Email for Let's Encrypt notifications
+email = "admin@example.com"
+
+# Use staging for testing (avoid rate limits)
+staging = false
+
+# DNS provider for DNS-01 challenges
+dns_provider = "cloudflare"
+dns_api_token = "\${CLOUDFLARE_API_TOKEN}"
+
+# Certificate storage
+cert_path = "/etc/dstack/certs"
+
+# Renewal settings
+renewal_days = 30
+renewal_check_interval = "12h"`}
+
+ +### Certificate Transparency Monitoring + +
+

CT Log Monitoring:

+ 
{`# Check CT logs for your domain
+curl "https://crt.sh/?q=%.example.com&output=json" | jq '.'
+
+# Gateway automatic monitoring
+[monitoring]
+ct_log_check = true
+ct_log_interval = "1h"
+alert_webhook = "https://alerts.example.com/ct"`}
+
+ +--- + +## Advanced Networking Features + +### Multi-Region Deployment Architecture + +Deploy across multiple regions with optimized routing: + +```mermaid +graph TB + subgraph "US East" + GW1[Gateway US] + CVM1[CVMs US] + end + + subgraph "EU West" + GW2[Gateway EU] + CVM2[CVMs EU] + end + + subgraph "Asia Pacific" + GW3[Gateway AP] + CVM3[CVMs AP] + end + + subgraph "Global" + GLB[GeoDNS] + KMS[Global KMS] + end + + GLB -->|US Users| GW1 + GLB -->|EU Users| GW2 + GLB -->|AP Users| GW3 + + GW1 -.->|Mesh VPN| GW2 + GW2 -.->|Mesh VPN| GW3 + GW3 -.->|Mesh VPN| GW1 + + CVM1 -->|RA-TLS| KMS + CVM2 -->|RA-TLS| KMS + CVM3 -->|RA-TLS| KMS +``` + +### Load Balancing Strategies + +
+

Load Balancing Methods:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodAlgorithmUse Case
Round RobinSequential distributionEqual server capacity
Least ConnectionsRoute to least busyLong-lived connections
IP HashConsistent routingSession affinity needed
GeographicNearest regionGlobal deployments
+
+
+ +### Service Mesh Integration + +For complex microservices deployments: + +
+

Istio Integration Example:

+ 
{`# Istio integration example
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: dstack-app
+spec:
+  hosts:
+  - myapp.example.com
+  http:
+  - match:
+    - headers:
+        x-dstack-verified:
+          exact: "true"
+    route:
+    - destination:
+        host: myapp-service
+        port:
+          number: 8080`}
+
diff --git a/docs/concepts/overview.mdx b/docs/concepts/overview.mdx new file mode 100644 index 00000000..edddb85c --- /dev/null +++ b/docs/concepts/overview.mdx @@ -0,0 +1,212 @@ +--- +title: "Component Summary" +description: "dstack is an open-source platform that transforms any Docker container into a secure Trusted Execution Environment (TEE) deployment with zero code changes. This overview introduces the fundamental concepts and guides you to the detailed documentation you need." +--- + + + +## Understanding TEEs and Confidential Computing + +At its core, dstack leverages **Trusted Execution Environments** - hardware-secured computing environments that protect your code and data even from privileged system access. Think of a TEE as a hardware-enforced safe room for your applications. + +**Current TEE Support:** dstack currently supports [Intel TDX (Trust Domain Extensions)](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html) with planned support for AMD SEV-SNP and ARM Confidential Compute Architecture. + +--- + +## DStack main components + +dstack's architecture centers around five primary components that work together to provide secure deployment: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentPrimary RoleWhen You'll Use It
dstack-vmmManages TEE virtual machinesEvery deployment
dstack-gatewaySecure HTTPS gatewayWeb-accessible applications
dstack-kmsCryptographic key managementSecure data handling
dstack-guest-agentContainer management in TEERuntime operations
dstack-osMinimal secure operating systemTEE environment foundation
+
+ +**Next:** Learn about each component's basic role in [Basic Components](/docs/concepts/basic-components) + +--- + +# The DStack Approach + +

+ dstack abstracts the complexity of TEE deployment through a familiar Docker-centric workflow: +

+
+
+ Docker Logo +
+
+
    +
  1. Start with existing containers – Use your current Docker containers and compose files
    2. +
  2. Deploy to secure infrastructure – dstack handles TEE provisioning and configuration
    3. +
  3. Get automatic security – Memory encryption, attestation, and secure networking included
    4. +
  4. Verify independently – Cryptographic proof of security available to anyone
    5. +
+
+
+ +--- + +# Security Model + +dstack implements a **zero-trust architecture** where security doesn't depend on trusting infrastructure providers, system administrators, or even the host operating system. + +
+
+

+ ✅ what we trust +

+
+
- TEE hardware (cryptographically verified)
+
- Open-source code (auditable by anyone)
+
- Blockchain consensus (decentralized verification)
+
- Mathematical proofs (attestation signatures)
+
+
+
+

+ ⚠️ what we don't trust +

+
+
- Host operating systems
+
- Cloud providers
+
- Network infrastructure
+
- System administrators
+
- Other applications on the same hardware
+
+
+
+
+ see system architecture for more security details +
+ +## Key Active Technologies + +dstack uses several advanced security mechanisms to guarantee the integrity, confidentiality, and portability of workloads across different environments: + +**Remote Attestation** +remote attestation is central to dstack's security model. It provides cryptographic proof that the Trusted Execution Environment (TEE) is genuine and that the application code hasn't been tampered with. This lets any party verify the integrity and authenticity of the TEE and the running code, ensuring the execution context matches expected measurements. This verifiable evidence is essential for building trust in distributed systems and is a core part of confidential computing. + +**Decentralized Key Management** +dstack uses decentralized methods to manage cryptographic keys, reducing reliance on any single provider or authority and improving resilience and security. + +**Immutable Deployments** +deployments in dstack are immutable, meaning application images and configurations can't be changed after deployment. This ensures consistency, prevents drift, and makes it easier to verify the integrity of running workloads. + + + for a comprehensive understanding of dstack's security framework, see the Security Model page. More technical details are available on the Core Components page. + + +# DStack Network Architecture + +dstack secures data in transit through a multi-tiered network stack, integrating four distinct security and isolation domains: + +**Public HTTPS** +Every public endpoint is fronted by automatically issued and renewed TLS certificates from [Let's Encrypt](https://letsencrypt.org/), delivering browser-to-edge encryption and hands-free domain routing. + +**WireGuard VPN** +A lightweight mesh of [WireGuard](https://www.wireguard.com/) tunnels secures node-to-node traffic, creating a zero-trust backbone that spans clouds, regions, and on-prem clusters with minimal latency overhead. + +**TDX Isolation** +Workloads run inside Intel [Trust Domain Extensions (TDX)](https://en.wikipedia.org/wiki/Trust_Domain_Extensions) confidential VMs. Each trust domain is hardware-isolated from the host hypervisor and other tenants; network interfaces are scoped and attested before any packet is accepted, blocking spoofing and side-channel attacks. + +**Application** +Inside each TDX enclave, containers use standard Docker/Kubernetes networking—services, virtual IPs, and sidecars—so existing micro-services communicate normally while inheriting all lower-layer protections. + + + understanding dstack's secure networking architecture and traffic routing—see the networking guide + + +## Documentation Navigation + +**Core concepts reading path** – follow this sequence to build comprehensive understanding: + + + + + +## What if i read everything and want to go even deeper? + +Before you jump into the advanced research and security topics, make sure you've gone through the next page on the basics of dstack's core components. understanding how the `/kms`, `/vmm`, and `/gateway` work together will give you much better intuition for the deeper material. + +Once you're comfortable with those, then we recommend moving on to [security and research](/docs/security-research/overview) for a look at the underlying security research and design decisions. + diff --git a/docs/dstack-gateway.md b/docs/dstack-gateway.md deleted file mode 100644 index 35aa44f8..00000000 --- a/docs/dstack-gateway.md +++ /dev/null @@ -1,49 +0,0 @@ -# Setup dstack-gateway for Production - -To set up dstack-gateway for production, you need a wildcard domain and SSL certificate. - -## Step 1: Setup wildcard domain - -Set up a second-level wildcard domain using Cloudflare; make sure to disable proxy mode and use **DNS Only**. - -![add-wildcard-domain](./assets/tproxy-add-wildcard-domain.jpg) - -## Step 2: Request a Wildcard Domain SSL Certificate with Certbot - -You need to get a Cloudflare API Key and ensure the API can manage this domain. - -You can check your Cloudflare API key and get `cf_zone_id` using this command: - -```shell -curl -X GET "https://api.cloudflare.com/client/v4/zones" -H "Authorization: Bearer " -H "Content-Type: application/json" | jq . -``` - -Open your `certbot.toml`, and update these fields: - -- `acme_url`: change to `https://acme-v02.api.letsencrypt.org/directory` -- `cf_api_token`: Obtain from Cloudflare -- `cf_zone_id`: Obtain from the API call above - -## Step 3: Run Certbot Manually and Get First SSL Certificates - -```shell -./certbot set-caa -./certbot renew -``` - -## Step 4: Update `gateway.toml` - -Focus on these five fields in the `core.proxy` section: - -- `cert_chain` & `cert_key`: Point to the certificate paths from the previous step -- `base_domain`: The wildcard domain for proxy -- `listen_addr` & `listen_port`: Listen to `0.0.0.0` and preferably `443` in production. If using another port, specify it in the URL - -For example, if your base domain is `gateway.example.com`, app ID is ``, listening on `80`, and dstack-gateway is on port 7777, the URL would be `https://-80.gateway.example.com:7777` - -## Step 5: Adjust Configuration in `vmm.toml` - -Open `vmm.toml` and adjust dstack-gateway configuration in the `gateway` section: - -- `base_domain`: Same as `base_domain` from `gateway.toml`'s `core.proxy` section -- `port`: Same as `listen_port` from `gateway.toml`'s `core.proxy` section \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 80a6bc0e..00000000 --- a/docs/faq.md +++ /dev/null @@ -1,33 +0,0 @@ -# FAQ - -## CVM status turns to `exited` immediately - -First, check the stderr output of the CVM. - -> [!TIP] -> To view the CVM's stderr, append `ch=stderr` to the end of the log URL. -> If the log URL is `/logs?id=&follow=true&ansi=false&lines=20` -> The stderr URL would be `/logs?id=&follow=true&ansi=false&lines=20&ch=stderr`. - -If you see an error message in CVM's stderr output: - -``` -Could not access KVM kernel module: Permission denied -gemu-system-x86_64: -accel kvm: failed to initialize kvm: Permission denied -``` - -This means your supervisor is not running with an account that belongs to the `libvirt` and `kvm` groups. You need to ensure your account is added to these two groups. You can check this by running the following command: - -```shell -id -``` - -If you are not in these groups, you likely won't have the necessary privileges to run QEMU. - -Once you have the required privileges, make sure the supervisor process is shut down: - -```shell -ps aux | grep supervisor | grep $(whoami) | grep -v grep -``` - -Log out of all your sessions and log back in. Check your groups with the `id` command, and this should resolve the issue. \ No newline at end of file diff --git a/docs/getting-started/exploring-dstack-notes.txt b/docs/getting-started/exploring-dstack-notes.txt new file mode 100644 index 00000000..3b9b792b --- /dev/null +++ b/docs/getting-started/exploring-dstack-notes.txt @@ -0,0 +1,85 @@ + + +## Exploring the dStack Repository + +The dstack repository is a comprehensive collection of tools, libraries, and services that support the platform’s mission of secure application deployment. + +Below, we’ll explore the various directories and their purposes, each linked to its location in the repository for easy reference. + +This structure represents the full scope of the dstack TEE platform. + +The [vmm/](https://github.com/Dstack-TEE/dstack/tree/master/vmm) directory houses the service that manages Confidential VMs on a bare TDX host, as described earlier. + +Complementing this, the [gateway/](https://github.com/Dstack-TEE/dstack/tree/master/gateway) directory contains the reverse proxy that secures TLS connections to CVMs. + +The [kms/](https://github.com/Dstack-TEE/dstack/tree/master/kms) directory provides the KMS server for key generation and management. + +[guest-agent/](https://github.com/Dstack-TEE/dstack/tree/master/guest-agent) includes the service running inside CVMs to support container operations. + +For system setup and security tasks, [dstack-util/](https://github.com/Dstack-TEE/dstack/tree/master/dstack-util) offers a CLI tool used within the guest environment for tasks like TDX quote generation, Runtime Measurement Register (RTMR) extension, and RA-TLS certificate generation. + +Remote attestation is a big part of dstack’s security model, supported by libraries like [ra-rpc/](https://github.com/Dstack-TEE/dstack/tree/master/ra-rpc) for Protocol Buffers RPC (pRPC). + +[ra-tls/](https://github.com/Dstack-TEE/dstack/tree/master/ra-tls) is for secure communication. + +Attestation-specific functionality is further enhanced by [tdx-attest/](https://github.com/Dstack-TEE/dstack/tree/master/tdx-attest), a guest library for obtaining TDX quotes and extending RTMR. + +[tdx-attest-sys/](https://github.com/Dstack-TEE/dstack/tree/master/tdx-attest-sys) provides low-level Rust bindings for Intel TDX attestation. + +Certificate management is handled through [cert-client/](https://github.com/Dstack-TEE/dstack/tree/master/cert-client) for requesting and verifying certificates in a TEE environment. + +[certbot/](https://github.com/Dstack-TEE/dstack/tree/master/certbot) is for automatic TLS certificate acquisition and renewal, specifically for the dstack-gateway. + +The [ct_monitor/](https://github.com/Dstack-TEE/dstack/tree/master/ct_monitor) directory ensures certificate issuance security by monitoring Certificate Transparency logs. + +Configuration and API support come from [load_config/](https://github.com/Dstack-TEE/dstack/tree/master/load_config), a utility for loading configurations across dstack components. + +[guest-api/](https://github.com/Dstack-TEE/dstack/tree/master/guest-api) is for guest-to-host interactions. + +[host-api/](https://github.com/Dstack-TEE/dstack/tree/master/host-api) is for managing guest environments from the host. + +Secure data handling is supported by [iohash/](https://github.com/Dstack-TEE/dstack/tree/master/iohash), an I/O hashing library. + +Key provisioning is managed through [key-provider-client/](https://github.com/Dstack-TEE/dstack/tree/master/key-provider-client). + +Its build utilities are in [key-provider-build/](https://github.com/Dstack-TEE/dstack/tree/master/key-provider-build). + +Shared resources across the ecosystem are defined in [dstack-types/](https://github.com/Dstack-TEE/dstack/tree/master/dstack-types), which contains type definitions and data structures. + +Communication needs are met by [http-client/](https://github.com/Dstack-TEE/dstack/tree/master/http-client), a secure HTTP client library. + +[sodiumbox/](https://github.com/Dstack-TEE/dstack/tree/master/sodiumbox) is a Rust implementation of libsodium’s sealed box encryption. + +Auditing and verification are supported by [cc-eventlog/](https://github.com/Dstack-TEE/dstack/tree/master/cc-eventlog) for handling Confidential Computing event logs. + +Service management within dstack is overseen by [supervisor/](https://github.com/Dstack-TEE/dstack/tree/master/supervisor), which monitors and controls running services. + +Utilities like [serde-duration/](https://github.com/Dstack-TEE/dstack/tree/master/serde-duration) provide serialization and deserialization for time durations in configurations. + +[mod-tdx-guest/](https://github.com/Dstack-TEE/dstack/tree/master/mod-tdx-guest) offers a TDX guest module for secure VM operations. + +For web framework integration, [rocket-vsock-listener/](https://github.com/Dstack-TEE/dstack/tree/master/rocket-vsock-listener) implements a VSOCK listener for Rocket. + +Developers can integrate with dstack using [python/](https://github.com/Dstack-TEE/dstack/tree/master/python) for Python bindings and utilities. + +The [sdk/](https://github.com/Dstack-TEE/dstack/tree/master/sdk) directory includes Software Development Kits for multiple languages. + +Within the SDK, you’ll find [go/](https://github.com/Dstack-TEE/dstack/tree/master/sdk/go) for Go integration. + +[js/](https://github.com/Dstack-TEE/dstack/tree/master/sdk/js) is for JavaScript and web applications. + +[python/](https://github.com/Dstack-TEE/dstack/tree/master/sdk/python) is for data science and machine learning. + +[rust/](https://github.com/Dstack-TEE/dstack/tree/master/sdk/rust) is for systems programming. + +Additional resources include [docs/](https://github.com/Dstack-TEE/dstack/tree/master/docs) for platform documentation. + +[basefiles/](https://github.com/Dstack-TEE/dstack/tree/master/basefiles) is for base file templates used in system initialization. + +[.github/](https://github.com/Dstack-TEE/dstack/tree/master/.github) is for GitHub configuration files managing CI/CD pipelines. + +Hardware-related utilities are found in [lspci/](https://github.com/Dstack-TEE/dstack/tree/master/lspci) for PCI device inspection. + +Testing is supported by [test-scripts/](https://github.com/Dstack-TEE/dstack/tree/master/test-scripts) for validating dstack functionality. + +This comprehensive structure represents the full dstack TEE platform, providing everything needed to deploy containerized applications securely, from core services to developer tools, all backed by hardware-level security guarantees. \ No newline at end of file diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-of-dstack-advanced.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-of-dstack-advanced.mdx new file mode 100644 index 00000000..de377362 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-of-dstack-advanced.mdx @@ -0,0 +1,40 @@ +--- +title: "Full Dstack Deployment Guide" +description: "Originally Authored, by Kevin Wang edited by Dylan Kawalec from Phala Network" +--- + +
+ dstack advanced deployment architecture +
+ +
+
+
+

+ This document describes the deployment of DStack components on bare metal TDX hosts. + It contains steps to deploy dstack-kms and dstack-gateway into CVMs. +

+
+
+
+ +## Prerequisites + +
+
+

Hardware Requirements

+

Follow the TDX setup guide to setup the TDX host.

+
+
+

Software Requirements

+

Install cargo and rustc

+
+
diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-1.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-1.mdx new file mode 100644 index 00000000..c04bb729 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-1.mdx @@ -0,0 +1,13 @@ +--- +title: "Step 1: Clone and Setup Repository" +description: "Clone the DStack repository" +--- + + +
+

Clone the DStack repository

+ +```bash +git clone https://github.com/Dstack-TEE/dstack +``` +
\ No newline at end of file diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-2.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-2.mdx new file mode 100644 index 00000000..1543ce41 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-2.mdx @@ -0,0 +1,64 @@ +--- +title: "Step 2: Compile and Run dstack-vmm" +description: "Compile and run dstack-vmm" +--- + +
+

Build and Configuration

+ +```bash +cd dstack +cargo build --release -p dstack-vmm -p supervisor +mkdir -p vmm-data +cp target/release/dstack-vmm vmm-data/ +cp target/release/supervisor vmm-data/ +cd vmm-data/ +``` + +
+

Create vmm.toml configuration:

+
+ +```bash +# create vmm.toml. Edit the config as needed. +cat < vmm.toml +address = "unix:./vmm.sock" +reuse = true +image_path = "./images" +run_path = "./run/vm" + +[cvm] +kms_urls = ["https://kms.test2.dstack.phala.network:9201"] +gateway_urls = [] +cid_start = 30000 +cid_pool_size = 1000 + +[cvm.port_mapping] +enabled = true +address = "127.0.0.1" +range = [ + { protocol = "tcp", from = 1, to = 20000 }, + { protocol = "udp", from = 1, to = 20000 }, +] + +[host_api] +port = 9300 +EOF +``` + +
+

Download Guest OS images:

+
+ +```bash +# Download Guest OS images +DSTACK_VERSION=0.5.2 +wget "https://github.com/Dstack-TEE/meta-dstack/releases/download/v${DSTACK_VERSION}/dstack-${DSTACK_VERSION}.tar.gz" +mkdir -p images/ +tar -xvf dstack-${DSTACK_VERSION}.tar.gz -C images/ +rm -f dstack-${DSTACK_VERSION}.tar.gz + +# run dstack-vmm +./dstack-vmm -c vmm.toml +``` +
\ No newline at end of file diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-3.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-3.mdx new file mode 100644 index 00000000..44eb0a33 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-3.mdx @@ -0,0 +1,33 @@ +--- +title: "Step 3: Deploy the KmsAuth Contract" +description: "Deploy the KmsAuth Contract" +--- + +
+
+

+ A KMS node requires a KMSAuth contract to be deployed on the Ethereum-compatible network. +

+
+ +```bash +cd dstack/kms/auth-eth +npm install +npx hardhat compile +PRIVATE_KEY= npx hardhat kms:deploy --network phala +``` + +
+

Expected Output:

+
+ 
+Deploying proxy...
+Waiting for deployment...
+KmsAuth Proxy deployed to: 0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875
+Implementation deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
+Deployment completed successfully
+Transaction hash: 0xd413d01a0640b6193048b0e98afb7c173abe58c74d9cf01f368166bc53f4fefe
+
+
+
+
diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-4.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-4.mdx new file mode 100644 index 00000000..d07ee0f9 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-4.mdx @@ -0,0 +1,155 @@ +--- +title: "Step 4: Deploy KMS into CVM" +description: "Deploy KMS into CVM" +--- + +
+

The dstack-vmm is running now. Open another terminal and go to the kms/dstack-app/ directory:

+ +```bash +cd dstack/kms/dstack-app/ +./deploy-to-vmm.sh +``` + +
+

Configure Environment Variables

+

Edit the .env file with required variables:

+
+ +
+``` +# .env +VMM_RPC=unix:../../vmm-data/vmm.sock +KMS_CONTRACT_ADDR=0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875 +KMS_RPC_ADDR=0.0.0.0:9201 +GUEST_AGENT_ADDR=127.0.0.1:9205 +ETH_RPC_URL=https://rpc.phala.network +GIT_REV=HEAD +OS_IMAGE=dstack-0.5.2 +IMAGE_DOWNLOAD_URL=https://files.kvin.wang/images/mr_{OS_IMAGE_HASH}.tar.gz +``` +
+ +
+

+ Important: Set the KMS_CONTRACT_ADDR to the address from the previous step and ensure IMAGE_DOWNLOAD_URL points to the correct dstack OS image for hash verification. +

+
+ +
+

Run deployment script again:

+

After configuring the .env file, run the script again to deploy:

+
+ +
+ 
+App compose file created at: .app-compose.json
+Compose hash: ec3d427f62bd60afd520fce0be3b368aba4516434f2ff761f74775f871f5b6e3
+Deploying KMS to dstack-vmm...
+App ID: ec3d427f62bd60afd520fce0be3b368aba451643
+Created VM with ID: f5299298-bf4f-43c0-839c-88c755391f3c
+
+
+
+ +### Monitor KMS Deployment + +
+

Check KMS CVM Status:

+ +```bash +cd ../../vmm-data/ +tail -f run/vm/f5299298-bf4f-43c0-839c-88c755391f3c/serial.log +``` + +
+

Wait for KMS Ready Signal:

+
+ 
+br-1df48b1c448a: port 2(veth36ab5cb) entered forwarding state
+app-compose.sh[882]:  Container dstack-kms-1  Started
+app-compose.sh[688]: Pruning unused images
+app-compose.sh[8347]: Total reclaimed space: 0B
+app-compose.sh[688]: Pruning unused volumes
+app-compose.sh[8356]: Total reclaimed space: 0B
+[  OK  ] Finished App Compose Service.
+[  OK  ] Reached target Multi-User System.
+         Starting Record Runlevel Change in UTMP...
+[  OK  ] Finished Record Runlevel Change in UTMP.
+
+
+
+
+ +### KMS Bootstrap Process + +
+
+
+

Access KMS Interface

+

Open your browser and navigate to:

+
+ http://127.0.0.1:9201/ +
+
    +
  1. Click the Bootstrap button
    2. +
  2. Fill in the domain serving the KMS (e.g., kms.test2.dstack.phala.network)
    3. +
  3. Click [Bootstrap] → [Finish setup]
    4. +
+
+
+
+ KMS Bootstrap Interface +
+
+
+ +
+
+
+

Bootstrap Result

+

+ After successful bootstrap, you'll see the public key and corresponding TDX quote: +

+
+

Next Step: Set the KMS info in the kms-auth-contract using the displayed values.

+
+
+
+
+ KMS Bootstrap Result +
+
+
+
+ +
+
+ KMS Auth Contract Configuration +
+

+ Configure the KMS info in the auth contract interface +

+
+ +
+

+ Success! The KMS instance is now ready to use. +

+
+
diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-5.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-5.mdx new file mode 100644 index 00000000..5740b103 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-5.mdx @@ -0,0 +1,153 @@ +--- +title: "Step 5: Deploy dstack-gateway in CVM" +description: "Deploy dstack-gateway in CVM" +--- + +
+

dstack-gateway can be deployed as a dstack app in the same host as the KMS or in a different host.

+ +

Add OS Image Hash to KMS Whitelist

+ +
+

+ In order to run user workloads that use the KMS, the OS image hash must be added to the KMS whitelist. +

+
+ +

The os_image_hash is generated during the image build process and stored in digest.txt:

+ +```bash +cd dstack/kms/auth-eth +npx hardhat kms:add-image --network phala --mr +``` + +

Register dstack-gateway in KMS

+ +```bash +cd dstack/kms/auth-eth +npx hardhat app:deploy --network phala +``` + +
+

Expected Output:

+
+ 
+Deploying proxy...
+Waiting for deployment...
+AppAuth Proxy deployed to: 0x539D0d59D1742780De41b85b2c3674b24369e292
+Implementation deployed to: 0x5aC1671E1Df54994D023F0B05806821d6D84e086
+Deployment completed successfully
+Transaction hash: 0xceac2ac6d56a40fef903b947d3a05df42ccce66da7f356c5d54afda68277f9a9
+Waiting for transaction 0xe144e9007208079e5e82c04f727d2383c58184e74d4f860e62557b5f330ab832 to be confirmed...
+App registered in KMS successfully
+Registered AppId: 0x31884c4b7775affe4c99735f6c2aff7d7bc6cfcd
+
+
+
+
+ +### Configure and Deploy Gateway + +
+

Initialize Gateway Deployment

+ +```bash +cd ../../gateway/dstack-app/ +./deploy-to-vmm.sh +``` + +
+

Configure Environment Variables

+

Edit the .env file with required variables:

+
+ +
+```bash +# .env +VMM_RPC=unix:../../vmm-data/vmm.sock + +# Cloudflare API token for DNS challenge used to get the SSL certificate. +CF_API_TOKEN=your_cloudflare_api_token +CF_ZONE_ID=your_zone_id + +# Service domain +SRV_DOMAIN=test2.dstack.phala.network + +# Public IP address +PUBLIC_IP=$(curl -s ifconfig.me) + +# Gateway application ID. Register the app in KmsAuth first to get the app ID. +GATEWAY_APP_ID=0x31884c4b7775affe4c99735f6c2aff7d7bc6cfcd + +# Whether to use ACME staging (yes/no) +ACME_STAGING=yes + +# Subnet index. 0~15 +SUBNET_INDEX=0 + +# My URL. The URL will be synced to other nodes in the cluster so that each node can discover other nodes. +MY_URL=https://gateway.test2.dstack.phala.network:9202 + +# Bootnode URL. If you want to deploy a multi-node dstack-gateway cluster, set the bootnode URL to the URL of another node already deployed or planed to be deployed later. +BOOTNODE_URL=https://gateway.test2.dstack.phala.network:9202 + +# DStack OS image name +OS_IMAGE=dstack-0.5.2 + +# Set defaults for variables that might not be in .env +GIT_REV=HEAD + +# Port configurations +GATEWAY_RPC_ADDR=0.0.0.0:9202 +GATEWAY_ADMIN_RPC_ADDR=127.0.0.1:9203 +GATEWAY_SERVING_ADDR=0.0.0.0:9204 +GUEST_AGENT_ADDR=127.0.0.1:9206 +WG_ADDR=0.0.0.0:9202 +``` +
+ +
+

Deployment Confirmation

+

After running the script again, you'll see a confirmation prompt:

+
+ 
+App compose file created at: .app-compose.json
+Compose hash: 700a50336df7c07c82457b116e144f526c29f6d8f4a0946b3e88065c9beba0f4
+Configuration:
+VMM_RPC: unix:../../build/vmm.sock
+SRV_DOMAIN: test5.dstack.phala.network
+PUBLIC_IP: 66.220.6.113
+GATEWAY_APP_ID: 31884c4b7775affe4c99735f6c2aff7d7bc6cfcd
+MY_URL: https://gateway.test5.dstack.phala.network:9202
+BOOTNODE_URL: https://gateway.test2.dstack.phala.network:9202
+SUBNET_INDEX: 0
+WG_ADDR: 0.0.0.0:9202
+GATEWAY_RPC_ADDR: 0.0.0.0:9202
+GATEWAY_ADMIN_RPC_ADDR: 127.0.0.1:9203
+GATEWAY_SERVING_ADDR: 0.0.0.0:9204
+GUEST_AGENT_ADDR: 127.0.0.1:9206
+Continue? [y/N]
+
+
+
+ +
+

+ Important: Don't press 'y' yet! First add the compose hash to the AppAuth contract. +

+
+ +
+

Add Compose Hash to Contract

+
+ +```bash +npx hardhat app:add-hash --network phala --app-id 0x31884c4b7775affe4c99735f6c2aff7d7bc6cfcd 0x700a50336df7c07c82457b116e144f526c29f6d8f4a0946b3e88065c9beba0f4 +``` + +
+

+ After the transaction is confirmed, you can press 'y' to continue the deployment. +

+
+
\ No newline at end of file diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-6.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-6.mdx new file mode 100644 index 00000000..c5480429 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-6.mdx @@ -0,0 +1,35 @@ +--- +title: "Step 6: Deploy Additional VMM Instances" +description: "Deploy Additional VMM Instances" +--- + +
+

Deploy dstack-vmm on other TDX hosts to serve user workloads

+ +

After the KMS and dstack-gateway are deployed, you can deploy dstack-vmm on other TDX hosts to serve user workloads.

+ +
+
+

terminal # 3

+

Open new terminal for the vmm

+
+ +
+

Update Configuration

+

Edit the vmm.toml file to set the KMS and dstack-gateway URLs:

+ +
+```toml +# vmm.toml +[cvm] +kms_urls = ["https://kms.test2.dstack.phala.network:9201"] +gateway_urls = ["https://gateway.test2.dstack.phala.network:9202"] +``` +
+
+
+ +
+

Then restart the dstack-vmm to apply the new configuration.

+
+
diff --git a/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-7.mdx b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-7.mdx new file mode 100644 index 00000000..872ec30a --- /dev/null +++ b/docs/getting-started/first-deployment-steps/advanced-deloyment-steps/deployment-step-7.mdx @@ -0,0 +1,134 @@ +--- +title: "Step 7: Deploy Applications" +description: "Deploy Applications" +--- + +
+

Deploy app on the dstack-vmm

+ +

After the dstack-vmm is ready, you can deploy an app following these steps:

+ +### 1. On-chain Registration + +
+

Registration Process

+
+
+
Step 1: Deploy AppAuth Contract
+

Deploy an App's control contract AppAuth. Use the reference contract or develop your own implementing the IAppAuth interface.

+
+
+
Step 2: Register App
+

Call KmsAuth.registerApp(appAuthAddress) to register and obtain the App Id.

+
+
+
+ +```bash +git clone https://github.com/Dstack-TEE/dstack +cd dstack/kms/auth-eth +npm install +npx hardhat compile +export PRIVATE_KEY= +export KMS_CONTRACT_ADDRESS=0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875 +npx hardhat app:deploy --allow-any-device --network phala +``` + +
+ 
+Deploying proxy...
+Waiting for deployment...
+AppAuth Proxy deployed to: 0xD4a546B1C7e63CD4CeD314b2C90108e49191A915
+Implementation deployed to: 0x5aC1671E1Df54994D023F0B05806821d6D84e086
+Deployment completed successfully
+Transaction hash: 0xceac2ac6d56a40fef903b947d3a05df42ccce66da7f356c5d54afda68277f9a9
+Waiting for transaction 0xe144e9007208079e5e82c04f727d2383c58184e74d4f860e62557b5f330ab832 to be confirmed...
+App registered in KMS successfully
+Registered AppId: 0xA35b434eE853fdf9c2Bf48Fa1583Ac1332d50255
+
+
+ +
+

+ Important: Note the AppId - you'll need this when deploying the CVM. If upgrading contracts in the future, backup the .openzeppelin/unknown-2035.json file. +

+
+ +### 2. Add App Compose Hash to Whitelist + +
+

Build app-compose.json and calculate its sha256 to get compose-hash. The compose hash can also be previewed in the dstack-vmm UI.

+
+ +```bash +export PRIVATE_KEY= +export KMS_CONTRACT_ADDRESS=0xFE6C45aE66344CAEF5E5D7e2cbD476286D651875 +npx hardhat app:add-hash --network phala --app-id 0xA35b434eE853fdf9c2Bf48Fa1583Ac1332d50255 0x44d9cb98aaa6ab11f5729fc7d6fd58117585e0e3fbec621612dcee6b2dfbcde5 +``` + +### 3. Deploy Instances using dstack-vmm + +
+
+

Deployment Configuration

+
    +
  • + + Select image dstack-0.4.2 +
    • +
  • + + Fill in the AppId from contract deployment +
    • +
  • + + Memory requirement: ≥ 3G or exactly = 2G +
    • +
+
+ +
+
+ App Deployment Interface +
+
+
+ +
+
+
+

Access Your Application

+

+ After the app starts normally, click [Board] to access. You can find the connections to dstack-gateway nodes, meaning that the app is now reachable from the internet. +

+
+
+
+ Application Dashboard +
+
+
+
+
+ +
+
+ + + +

Deployment Complete!

+
+

+ You have successfully deployed a complete dstack infrastructure with KMS, Gateway, and VMM components. Your applications are now running in secure Trusted Execution Environments and accessible through the internet. +

+
\ No newline at end of file diff --git a/docs/getting-started/first-deployment-steps/deploying-applications.mdx b/docs/getting-started/first-deployment-steps/deploying-applications.mdx new file mode 100644 index 00000000..74fe8ecf --- /dev/null +++ b/docs/getting-started/first-deployment-steps/deploying-applications.mdx @@ -0,0 +1,36 @@ +--- +title: "Understanding the DStack Deployment UI Guide" +description: "Complete guide to deploying containerized applications to dstack with step-by-step instructions" +--- +> We've come a long way from the first steps of installing dstack. Now, let's deploy your first application. + +> If you already have access to a dstack host (for example, someone else has installed and set up the hardware and dstack runtime for you), you can deploy your application directly to their dstack instance. +> +> If you need to review or complete the installation and setup steps for your own dstack host, go back to the previous section: [Step 4 – Install dstack Runtime](/docs/getting-started/install/step-4-install-dstack-runtime). That section covers the full dstack installation and build process before you reach this deployment guide. + +## 4 – Deploying Your First Application: Step-by-Step + +Follow these clear steps to deploy your first application using the dstack UI. Each phase is illustrated with a screenshot and a brief explanation. + +| Step | What to Do & What You’ll See | +|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **1. Configure Container** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step13.png)
Select the container image you want to deploy and specify which ports should be exposed. | +| **2. Set Basic Settings** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step14.png)
Enter a name for your application and choose the deployment type (e.g., web service, job, etc.). | +| **3. Secure Environment** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step15.png)
Add any environment variables your app needs. Mark sensitive variables to encrypt them for extra security. | +| **4. Review Variables** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step16.png)
Double-check all environment variables and settings. Make sure everything is correct before proceeding. | +| **5. Launch Application** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step17.png)
Click to deploy your application. dstack will start the deployment process on the infrastructure. | +| **6. Check Deployment Status** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step18.png)
Once deployed, your application will appear in the deployment list. You can monitor its status here. | + +--- + +## 5 – Verify & Explore + +After deploying your application, follow these steps to make sure everything is working as expected: + +| What to Check | What to Do & What You’ll See | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **VMM Status** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step23.png)
Open the VMM dashboard to confirm your application appears in the list and is marked as running. [See example screenshot](/docs/getting-started/first-deployment-steps/step-install-guide/step23.png). | +| **System Logs** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step24.png)
Check the system and application logs for any errors or warnings. This helps you verify that the node and your app started up correctly. [See example screenshot](/docs/getting-started/first-deployment-steps/step-install-guide/step24.png). | +| **Live Monitoring**| ![](/docs/getting-started/first-deployment-steps/step-install-guide/step25.logs.png)
Use the live log viewer to watch your application’s output in real time. This is useful for troubleshooting and confirming your app is running as expected. [See example screenshot](/docs/getting-started/first-deployment-steps/step-install-guide/step25.logs.png). | +| **Access Check** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step26.png)
Test your application’s endpoint (such as a web URL or API) to make sure it is accessible from your browser or API client. [See example screenshot](/docs/getting-started/first-deployment-steps/step-install-guide/step26.png). | +| **Final Validation** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step28.png)
Your application is now fully deployed and running on dstack. For reference, here’s a live example: [see deployed app](https://13bed0f2e9d7529a6eba06f0ebff51c8e23953c2-3000.dstack-prod6.phala.network/). Visit your own app’s endpoint or UI to confirm it loads and works as expected. If you can see and interact with your app, your deployment is complete and your app is running securely on a confidential VM. | diff --git a/docs/getting-started/first-deployment-steps/fd-1.mdx b/docs/getting-started/first-deployment-steps/fd-1.mdx new file mode 100644 index 00000000..63871a1a --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-1.mdx @@ -0,0 +1,68 @@ +--- +title: "How to Pull & inspect the example container image" +description: "Prepare your application for deployment" +--- + +## Step 1: + +### Option A: Use Our Example Application + +Create a new directory for your project: + +```bash +mkdir ~/my-first-dstack-app +cd ~/my-first-dstack-app +``` + +Create a simple Python Flask application: + +```python +# app.py +from flask import Flask, jsonify +import os +import socket + +app = Flask(__name__) + +@app.route('/') +def hello(): + return jsonify({ + 'message': 'Hello from dstack! 🔒', + 'secure': 'Running in a Trusted Execution Environment', + 'hostname': socket.gethostname(), + 'environment': os.environ.get('DSTACK_ENV', 'production') + }) + +@app.route('/health') +def health(): + return jsonify({'status': 'healthy'}), 200 + +if __name__ == '__main__': + app.run(host='0.0.0.0', port=8080) +``` + +Create a requirements file: + +```txt +# requirements.txt +flask==3.0.0 +gunicorn==21.2.0 +``` + +Create a Dockerfile: + +```dockerfile +# Dockerfile +FROM python:3.11-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY app.py . + +EXPOSE 8080 + +CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "2", "app:app"] +``` diff --git a/docs/getting-started/first-deployment-steps/fd-2.mdx b/docs/getting-started/first-deployment-steps/fd-2.mdx new file mode 100644 index 00000000..0abde2e2 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-2.mdx @@ -0,0 +1,62 @@ +--- +title: "How to Write the dstack deployment manifest" +description: "Create a docker-compose.yml file" +--- + +## Step 2 + +Create a `docker-compose.yml` file to define your application: + +```yaml +# docker-compose.yml +version: '3.8' + +services: + web: + build: . + # Or use a pre-built image: + # image: your-dockerhub-username/your-app:latest + ports: + - "8080:8080" + environment: + - DSTACK_ENV=production + - LOG_LEVEL=info + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + restart: unless-stopped +``` + + +#### if you were curious, yes you can deploy a Multi-container application too + +For applications with multiple services: + +```yaml +version: '3.8' + +services: + web: + build: ./web + ports: + - "8080:8080" + environment: + - DATABASE_URL=postgresql://user:pass@db:5432/mydb + depends_on: + - db + + db: + image: postgres:15-alpine + environment: + - POSTGRES_USER=user + - POSTGRES_PASSWORD=pass + - POSTGRES_DB=mydb + volumes: + - db_data:/var/lib/postgresql/data + +volumes: + db_data: +``` diff --git a/docs/getting-started/first-deployment-steps/fd-3.mdx b/docs/getting-started/first-deployment-steps/fd-3.mdx new file mode 100644 index 00000000..09312eed --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-3.mdx @@ -0,0 +1,131 @@ +--- +title: "How to Sign & push the image to your private registry" +description: "Deploy via Web UI & Monitor with CLI Tools" +--- + +## Step 3: Access Dashboard & Monitor Deployments + +### Access the dstack Dashboard + +1. Open your browser and navigate to http://localhost:9080 +2. You should see the dstack management interface + +
+ dstack Dashboard +
+ +### Create New Deployment + +Click **"Deploy New Application"** and fill in the deployment form: + +| Field | Value | +|-------|-------| +| **Application Name** | my-first-app | +| **Description** | My first secure application | +| **Docker Compose File** | Upload your `docker-compose.yml` | + +
+ deployment progress +
+ +--- + +## CLI Tools for Monitoring Deployments + +### dstack-vmm CLI + +Monitor VMs and container deployments: + +```bash +# List all VMs and their status +python3 vmm-cli.py --url http://localhost:8080 lsvm + +# List VMs with detailed information +python3 vmm-cli.py --url http://localhost:8080 lsvm -v + +# Show VM logs (useful for monitoring deployment progress) +python3 vmm-cli.py --url http://localhost:8080 logs + +# Follow logs in real-time +python3 vmm-cli.py --url http://localhost:8080 logs --follow + +# List available OS images +python3 vmm-cli.py --url http://localhost:8080 lsimage +``` + +### Supervisor CLI + +Monitor processes within containers: + +```bash +# List all running processes +supervisor-client --base-url unix:/var/run/supervisor.sock list + +# Get detailed information about a specific process +supervisor-client --base-url unix:/var/run/supervisor.sock info + +# Health check +supervisor-client --base-url unix:/var/run/supervisor.sock ping +``` + +### dstack-util CLI + +For advanced monitoring and attestation: + +```bash +# Get TDX report (for attestation verification) +echo -n "report_data" | dstack-util report + +# Generate TDX quote (for remote attestation) +echo -n "report_data" | dstack-util quote + +# Show current RTMR measurements +dstack-util show +``` + +--- + +## Monitor Deployment Progress + +The deployment process involves several steps: + +
+
+
+
1
+ Creating Confidential VM +
+
+
2
+ Setting up secure environment +
+
+
3
+ Pulling Docker images +
+
+
4
+ Starting containers +
+
+
✓
+ Application running +
+
+
+ +Use the CLI tools above to monitor each step and troubleshoot any issues during deployment. diff --git a/docs/getting-started/first-deployment-steps/fd-5.mdx b/docs/getting-started/first-deployment-steps/fd-5.mdx new file mode 100644 index 00000000..00bdeda7 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-5.mdx @@ -0,0 +1,99 @@ +--- +title: "How to Verify a TDX Attestation & perform a remote proof of trust" +description: "Access Your Application" +--- + +## Step 4: Access Your Application + +Once deployed, your application is accessible through the dstack gateway. + +### Find Your Application URL + +1. In the dashboard, click on your deployment +2. Look for the **"Endpoints"** section +3. You'll see URLs like: + - Internal: `http://cvm-abc123.local:8080` + - External: `https://my-first-app.app.example.com` + +### Test Your Application + +```bash +# Test the application +curl https://my-first-app.app.example.com + +# Expected response: +{ + "message": "Hello from dstack! 🔒", + "secure": "Running in a Trusted Execution Environment", + "hostname": "cvm-abc123", + "environment": "production" +} +``` + +--- + +## Additional Access Methods + +### Gateway URL Patterns + +Beyond basic URLs, the gateway supports multiple patterns: + +- `.` → port 80 +- `s.` → port 443 (TLS passthrough) +- `-.` → custom port +- `-s.` → custom port with TLS passthrough + +### Programmatic Access via SDKs + +Interact with dstack services programmatically: + +**JavaScript/TypeScript:** +```javascript +import { DstackClient } from '@dstack/sdk' +const client = new DstackClient() +const key = await client.getKey('/path', 'purpose') +``` + +**Python:** +```python +from dstack_sdk import DstackClient +client = DstackClient() +key = client.get_key('/path', 'purpose') +``` + +**Go:** +```go +client := dstack.NewClient() +key, err := client.GetKey("/path", "purpose") +``` + +### Direct CVM Access + +**SSH into CVM** (development images only): +```bash +ssh root@ # Get IP from gateway dashboard +``` + +**Unix Socket Communication:** +```bash +# Mount socket in docker-compose.yaml +volumes: + - /var/run/dstack.sock:/var/run/dstack.sock +``` + +### Management Dashboards + +- **VMM Dashboard**: `http://localhost:9080` - deployment management +- **Gateway Dashboard**: Monitor CVM connections and WireGuard status +- **Container Logs**: HTTP endpoints with filtering options + +### Log Access + +```bash +# Via VMM CLI +python3 vmm-cli.py logs --follow + +# Via HTTP API +curl http://localhost:8080/logs?id=&follow=true +``` + diff --git a/docs/getting-started/first-deployment-steps/fd-6.mdx b/docs/getting-started/first-deployment-steps/fd-6.mdx new file mode 100644 index 00000000..81cbfce2 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-6.mdx @@ -0,0 +1,136 @@ +--- +title: "Expose an API endpoint via the Gateway" +description: "Verify Security & Attestation" +--- + +## Step 6: Verify Security & Expose API Endpoints + +One of dstack's key features is verifiable security. Let's verify your application is running in a genuine TEE and expose secure API endpoints. + +### Get Attestation Quote Using dstack SDK + +The dstack JavaScript SDK provides direct access to attestation functionality: + +```javascript +// verify-deployment.js +const { DstackClient } = require('dstack-sdk'); + +async function verifyDeployment() { + // Connect to dstack guest agent (default Unix socket) + const client = new DstackClient(); + + // Get attestation quote with report data + const quote = await client.getQuote('your-report-data'); + console.log('Attestation Quote:', quote.quote); + console.log('Event Log:', quote.event_log); + + // Replay RTMRs for verification + const rtmrs = quote.replayRtmrs(); + console.log('RTMRs:', rtmrs); + + // Get application info + const info = await client.info(); + console.log('App ID:', info.app_id); + console.log('Instance ID:', info.instance_id); + console.log('TCB Info:', info.tcb_info); +} + +verifyDeployment(); +``` + +### Container Setup + +To use dstack SDK in your Docker container, mount the dstack socket: + +```yaml +version: '3' +services: + your-app: + image: your-image + volumes: + - /var/run/dstack.sock:/var/run/dstack.sock + ports: + - "8080:8080" +``` + +### Alternative: Direct HTTP API + +You can also access attestation via HTTP API: + +```bash +# Get attestation quote +curl --unix-socket /var/run/dstack.sock \ + http://dstack/GetQuote \ + -H "Content-Type: application/json" \ + -d '{"report_data": "1234deadbeaf"}' + +# Get application info +curl --unix-socket /var/run/dstack.sock \ + http://dstack/Info +``` + +### Expose Secure API Endpoints + +Create an API endpoint that provides attestation data: + +```javascript +// app.js - Express.js example +const express = require('express'); +const { DstackClient } = require('dstack-sdk'); + +const app = express(); +const client = new DstackClient(); + +// Endpoint to get attestation quote +app.get('/api/attestation', async (req, res) => { + try { + const reportData = req.query.report_data || 'default-report-data'; + const quote = await client.getQuote(reportData); + res.json({ + success: true, + quote: quote.quote, + event_log: quote.event_log, + rtmrs: quote.replayRtmrs() + }); + } catch (error) { + res.status(500).json({ success: false, error: error.message }); + } +}); + +// Endpoint to get app info +app.get('/api/info', async (req, res) => { + try { + const info = await client.info(); + res.json({ success: true, info }); + } catch (error) { + res.status(500).json({ success: false, error: error.message }); + } +}); + +app.listen(8080, () => { + console.log('API server running on port 8080'); +}); +``` + +### Verification Process + +For complete security verification: + +1. **Verify TDX Quote**: Use Intel's DCAP-QVL to verify the quote signature +2. **Check Measurements**: Validate MRTD and RTMRs against expected values +3. **Replay Event Log**: Use the `replayRtmrs()` method to verify RTMR3 contains correct app information +4. **Validate App Identity**: Ensure the app ID matches your deployment + +### Verify via Web Interface + +1. In the VMM dashboard, click on your deployment +2. Navigate to the **"Security"** tab +3. Click **"View Attestation Report"** +4. Use external TEE verification tools to validate the attestation + +### Gateway URL Access + +Your secure API endpoints will be accessible through dstack gateway URLs: + +- `https://.example.com/api/attestation` +- `https://.example.com/api/info` diff --git a/docs/getting-started/first-deployment-steps/fd-7.mdx b/docs/getting-started/first-deployment-steps/fd-7.mdx new file mode 100644 index 00000000..100fc74e --- /dev/null +++ b/docs/getting-started/first-deployment-steps/fd-7.mdx @@ -0,0 +1,99 @@ +--- +title: "How to Update, roll back, and tear down safely" +description: "Monitor Your Application" +--- + +## Step 7: + + +Monitor and troubleshoot + +### View Logs + +**From the Web Interface:** +1. Open VMM dashboard at `http://localhost:9080` +2. Click on your deployment +3. Go to the **"Logs"** tab for real-time logs + +**From the CLI:** +```bash +# Stream logs in real-time +python3 vmm-cli.py --url http://localhost:8080 logs --follow + +# Get last 100 lines +python3 vmm-cli.py --url http://localhost:8080 logs --lines 100 +``` + +**Direct HTTP API:** +```bash +curl 'http://.app.example.com:9090/logs/?follow=true&text=true×tamps=true' +``` + +### Check Application Status + +```bash +# List all VMs and their status +python3 vmm-cli.py --url http://localhost:8080 lsvm --verbose + +# List available images +python3 vmm-cli.py --url http://localhost:8080 lsimage +``` + +### VM Management + +```bash +# Start a VM +python3 vmm-cli.py --url http://localhost:8080 start + +# Stop a VM +python3 vmm-cli.py --url http://localhost:8080 stop + +# Remove a VM +python3 vmm-cli.py --url http://localhost:8080 remove +``` + +--- + +## Common Issues & Solutions + +### Application fails to start +```bash +# Check VM logs for errors +python3 vmm-cli.py --url http://localhost:8080 logs + +# Verify VM status +python3 vmm-cli.py --url http://localhost:8080 lsvm -v +``` + +### Cannot access application URL +```bash +# Check if VM is running +python3 vmm-cli.py --url http://localhost:8080 lsvm + +# Test connectivity +curl -I https://.example.com + +# Check gateway VM logs (find gateway VM ID first) +python3 vmm-cli.py --url http://localhost:8080 logs --follow +``` + +### Attestation verification fails +1. Ensure the CVM is fully initialized +2. Verify TDX is enabled on your hardware +3. Check app endpoint is accessible via Unix socket + +--- + +## What You've Accomplished + +✅ **Deployed** an application to a Trusted Execution Environment +✅ **Verified** it's running securely with attestation +✅ **Accessed** it through secure HTTPS endpoints +✅ **Monitored** logs and system status + +**Next Steps:** +- Deploy more applications: [Deploying Applications guide](/docs/getting-started/first-deployment-steps/deploying-applications.mdx) +- Get help: [Community](/docs/community-section/community.mdx) + +--- + diff --git a/docs/getting-started/first-deployment-steps/first-deployment.mdx b/docs/getting-started/first-deployment-steps/first-deployment.mdx new file mode 100644 index 00000000..c40a2721 --- /dev/null +++ b/docs/getting-started/first-deployment-steps/first-deployment.mdx @@ -0,0 +1,63 @@ +--- +title: "Application Deployment Overview" +description: "A practical walkthrough for deploying secure applications on your dstack infrastructure" +--- + +## Before You Begin + +| ✅ Checklist | Description | +| ---------------------- | ---------------------------------------------------------------------------- | +| dstack installed | Finished Installation guide | +| Environment configured | Finished Environment Setup guide | +| Services healthy | KMS, Gateway & VMM report status: healthy | +| TDX enabled | Host CPU supports Intel TDX and BIOS/Kernel options are enabled | +| Management UI up | [http://localhost:9080](http://localhost:9080) reachable | + + +# Deploying Applications on dstack + +--- + +> **🧭 Quick Path to Success with our Mini Guides** +> +> | Step | What You’ll Do | Link | +> | -------- | ---------------------------------------------- | --------------------------------------- | +> | **1** | Pull & inspect the example container image | [`Pull & inspect the example container image`](/docs/getting-started/first-deployment-steps/fd-1) | +> | **2** | Write the dstack deployment manifest | [`Write the dstack deployment manifest`](/docs/getting-started/first-deployment-steps/fd-2) | +> | **3** | Sign & push the image to your private registry | [`Sign & push the image to your private registry`](/docs/getting-started/first-deployment-steps/fd-3) | +> | **4** | Access the dstack dashboard & monitor deployments | [`Access the dstack dashboard & monitor deployments`](/docs/getting-started/first-deployment-steps/fd-3) | +> | **5** | Verify attestation & remote‑prove trust | [`Verify attestation & remote‑prove trust`](/docs/getting-started/first-deployment-steps/fd-5) | +> | **6** | Expose an API endpoint via the Gateway | [`Expose an API endpoint via the Gateway`](/docs/getting-started/first-deployment-steps/fd-6) | +> | **7** | Update, roll back, and tear down safely | [`Update, roll back, and tear down safely`](/docs/getting-started/first-deployment-steps/fd-7) | +> +> Skim the table, pick up at **Step 1**, and continue straight through **Step 7**. + +--- + +
+
+
+

+ 🎉 Milestone: by the end of Step 7 you will have a fully attested, externally reachable application running under hardware‑enforced confidentiality. +

+

+ note: estimated time depends on your setup and experience; no specific time allotted. +

+
+
+
+ +--- + +## Next Steps & Further Reading + +**Start here:** Step 1 — Pull the Example Application + +After each mini-guide, follow the **Next Step** banner to proceed in order. Skipping steps may leave your deployment unverified or insecure. + +**Further reading:** +- [System Architecture](/docs/concepts/architecture) – How all components fit together +- [Security Model](/docs/security-research/security-model) – Threat model & enclave guarantees +- [Read to Go Deployment Guides](/docs/tutorials/index-quick-start) – + +**Ready?** Jump to Step 1 and ship something real. diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step1.png b/docs/getting-started/first-deployment-steps/step-install-guide/step1.png new file mode 100644 index 00000000..52f57514 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step1.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step10.png b/docs/getting-started/first-deployment-steps/step-install-guide/step10.png new file mode 100644 index 00000000..adabce51 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step10.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step11.png b/docs/getting-started/first-deployment-steps/step-install-guide/step11.png new file mode 100644 index 00000000..96d00076 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step11.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step12.0.png b/docs/getting-started/first-deployment-steps/step-install-guide/step12.0.png new file mode 100644 index 00000000..943ed261 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step12.0.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step12.1.png b/docs/getting-started/first-deployment-steps/step-install-guide/step12.1.png new file mode 100644 index 00000000..8dcad0b6 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step12.1.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step12.2.png b/docs/getting-started/first-deployment-steps/step-install-guide/step12.2.png new file mode 100644 index 00000000..2a4b0d36 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step12.2.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step13.png b/docs/getting-started/first-deployment-steps/step-install-guide/step13.png new file mode 100644 index 00000000..d75c0e2a Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step13.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step14.png b/docs/getting-started/first-deployment-steps/step-install-guide/step14.png new file mode 100644 index 00000000..01706911 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step14.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step15.png b/docs/getting-started/first-deployment-steps/step-install-guide/step15.png new file mode 100644 index 00000000..417ddbc4 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step15.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step16.png b/docs/getting-started/first-deployment-steps/step-install-guide/step16.png new file mode 100644 index 00000000..514a9077 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step16.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step17.png b/docs/getting-started/first-deployment-steps/step-install-guide/step17.png new file mode 100644 index 00000000..efe88122 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step17.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step18.png b/docs/getting-started/first-deployment-steps/step-install-guide/step18.png new file mode 100644 index 00000000..94eb1892 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step18.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step19.png b/docs/getting-started/first-deployment-steps/step-install-guide/step19.png new file mode 100644 index 00000000..047b5573 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step19.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step2.png b/docs/getting-started/first-deployment-steps/step-install-guide/step2.png new file mode 100644 index 00000000..c1f9f02d Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step2.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step20.png b/docs/getting-started/first-deployment-steps/step-install-guide/step20.png new file mode 100644 index 00000000..ca1c6a4e Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step20.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step22.png b/docs/getting-started/first-deployment-steps/step-install-guide/step22.png new file mode 100644 index 00000000..4ba45930 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step22.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step23.png b/docs/getting-started/first-deployment-steps/step-install-guide/step23.png new file mode 100644 index 00000000..39990d14 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step23.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step24.png b/docs/getting-started/first-deployment-steps/step-install-guide/step24.png new file mode 100644 index 00000000..47bdfae3 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step24.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step25.logs.png b/docs/getting-started/first-deployment-steps/step-install-guide/step25.logs.png new file mode 100644 index 00000000..e9f09ef7 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step25.logs.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step26.png b/docs/getting-started/first-deployment-steps/step-install-guide/step26.png new file mode 100644 index 00000000..0c82e626 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step26.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step28.png b/docs/getting-started/first-deployment-steps/step-install-guide/step28.png new file mode 100644 index 00000000..d593260c Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step28.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step3.png b/docs/getting-started/first-deployment-steps/step-install-guide/step3.png new file mode 100644 index 00000000..9430cc71 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step3.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step4.0.png b/docs/getting-started/first-deployment-steps/step-install-guide/step4.0.png new file mode 100644 index 00000000..18d7a457 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step4.0.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step4.1.png b/docs/getting-started/first-deployment-steps/step-install-guide/step4.1.png new file mode 100644 index 00000000..ab03c3b0 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step4.1.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step4.2.png b/docs/getting-started/first-deployment-steps/step-install-guide/step4.2.png new file mode 100644 index 00000000..aaeebe5a Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step4.2.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step4.3.png b/docs/getting-started/first-deployment-steps/step-install-guide/step4.3.png new file mode 100644 index 00000000..51fe7e85 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step4.3.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step4.4.png b/docs/getting-started/first-deployment-steps/step-install-guide/step4.4.png new file mode 100644 index 00000000..6e925da5 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step4.4.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step5.png b/docs/getting-started/first-deployment-steps/step-install-guide/step5.png new file mode 100644 index 00000000..53ca00ca Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step5.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step6.png b/docs/getting-started/first-deployment-steps/step-install-guide/step6.png new file mode 100644 index 00000000..eebc831b Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step6.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step7.png b/docs/getting-started/first-deployment-steps/step-install-guide/step7.png new file mode 100644 index 00000000..01fcd511 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step7.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/step9.png b/docs/getting-started/first-deployment-steps/step-install-guide/step9.png new file mode 100644 index 00000000..eba88b5c Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/step9.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/terminal14.png b/docs/getting-started/first-deployment-steps/step-install-guide/terminal14.png new file mode 100644 index 00000000..82af6a8b Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/terminal14.png differ diff --git a/docs/getting-started/first-deployment-steps/step-install-guide/verifiable Compliance.png b/docs/getting-started/first-deployment-steps/step-install-guide/verifiable Compliance.png new file mode 100644 index 00000000..35206c86 Binary files /dev/null and b/docs/getting-started/first-deployment-steps/step-install-guide/verifiable Compliance.png differ diff --git a/docs/getting-started/install/app-jupiter-guide.mdx b/docs/getting-started/install/app-jupiter-guide.mdx new file mode 100644 index 00000000..86876830 --- /dev/null +++ b/docs/getting-started/install/app-jupiter-guide.mdx @@ -0,0 +1,140 @@ +--- +title: "Getting Started Now" +description: "this is how you and a remote host can quickly deploy apps to dstack" +--- +# Quick Start: Jupyter Notebook on dstack + +This is an exact guide on deploying a Jupyter Notebook on dstack where step by step we install, build and run the dstack straight from our local host, +and then we will be able to access our own TDX VM with Jupyter Notebook running on it. + + +
+ Jupyter Notebook Quick Start Banner +
+ + +--- + + +{/* Step 1: Open Tunnel and Access Dashboard */} +
+
+ 1 +

Open tunnel & access dashboard

+
+ + {`ssh -L13680:localhost:13680 @`} + +
+ this command lets you access the dstack dashboard running on your remote host. +
+
+ open in your browser: + http://127.0.0.1:13680 +
+
+ click "Deploy a new instance" to start your first container: + deploy a new instance +
+
+ + +--- + +## 📓 Check Your Jupyter Notebook Deployment + +First, let's confirm your VMM is running and ready. Open the dstack dashboard In Local Host in your browser. If everything is set up, you should see the Jupyter Notebook web page like this: +http://localhost/ + +jupyter notebook web page + + + + +### Step 2: Add the Docker Compose YAML + +Copy the following YAML and paste it into the "Docker Compose File" field in the dashboard: + + +{`services: + jupyter: + image: quay.io/jupyter/base-notebook + ports: + - 8080:8888 + volumes: + - /var/run/tappd.sock:/var/run/tappd.sock + environment: + - GRANT_SUDO=yes + user: root + command: "start-notebook.sh --NotebookApp.token=\${TOKEN}"`} + + +
+
+ 1 + Paste your Docker Compose YAML +
+ Paste Docker Compose and deploy +
+ Confirm the editor matches this example, then click "Deploy" to continue. +
+
+ + +### Step 3: Launch and Monitor + +
+ +
+ deployment launched in dashboard +
+ 1. Click Launch or Deploy in the dashboard. +
+
+ dstack will start your Jupyter Notebook. This usually takes 1–2 minutes. +
+
+ +
+ deployment in progress +
+ 2. Watch the progress +
+
    +
  • Check Serial Logs for VM boot details
    • +
  • See container status in the Containers tab
    • +
  • Scroll to the bottom of logs with Ctrl/Cmd+Down
    • +
+
+ Your deployment will appear in the dashboard as it starts up. +
+
+ +
+ + + +### Step 4: Open Your Jupyter Notebook + +After deployment, find your app's URL in the dashboard to access Jupyter Notebook. + + +https://<APP_ID>-<APP_PORT>.app.<host>:<host_port> + + diff --git a/docs/getting-started/install/installation.mdx b/docs/getting-started/install/installation.mdx new file mode 100644 index 00000000..de18e205 --- /dev/null +++ b/docs/getting-started/install/installation.mdx @@ -0,0 +1,14 @@ +--- +title: "Installation" +description: "Start here to install dstack. Follow the step-by-step guide to set up your environment." +--- + +# Installation Guide + +Welcome to the starting point for installing dstack. + +Follow the step-by-step instructions to set up dstack on your server: + +👉 [Start the installation process](/docs/getting-started/install/step-1-prerequisites) + +Each section covers a specific part of the setup, with tips and recommendations to help you deploy dstack smoothly. diff --git a/docs/getting-started/install/step-1-prerequisites.mdx b/docs/getting-started/install/step-1-prerequisites.mdx new file mode 100644 index 00000000..1b23e2dc --- /dev/null +++ b/docs/getting-started/install/step-1-prerequisites.mdx @@ -0,0 +1,47 @@ +--- +title: "Step 1: Prerequisites & System Requirements" +description: "Check hardware, OS, and software requirements before installing dstack." +--- + + +## Check your Hardware Requirements + +- **Bare-metal server with Intel TDX**: Your hardware must support Intel TDX. Prepare your firmware using the [canonical/tdx guide](https://github.com/canonical/tdx). _Note: VMs are not supported for secure enclaves._ +- **Public IPv4 address**: Required for HTTPS, API, and external access. +- **Specs**: At least **16GB RAM** & **100GB SSD**. For best results, aim for 32GB+ RAM and NVMe storage. +- **Domain name & DNS access**: You'll need a domain you can manage for Let's Encrypt and gateway access. + +## Software Requirements + +- **Linux kernel** 5.15+ (with TDX patches) +- **Supported OS**: Ubuntu 24.04 LTS (**strongly recommended**) or Ubuntu 22.04 LTS +- **Rust & Cargo**: Some dstack components are built from source. Install using the [official Rust installer](https://www.rust-lang.org/tools/install). +- **Node.js & npm**: For contract deployment tools, install from [nodejs.org](https://nodejs.org/). + +## Network & Ports + +| Port | Service | Direction | Purpose | +| ----- | --------- | --------- | --------------------------- | +| 9080 | Web UI | Inbound | dstack management interface | +| 9090 | API | Inbound | Application API access | +| 443 | HTTPS | Inbound | Secure web/app access | +| 80 | HTTP | Inbound | Redirect HTTP → HTTPS | +| 51820 | WireGuard | In/Out | Secure VPN for enclaves | + +## How to Check Intel TDX Support + +Run these commands. If you see TDX output, your hardware is ready: + +```bash +grep -E 'tdx|TDX' /proc/cpuinfo +sudo dmesg | grep -i tdx +``` + +--- + +## Recommendations +- Use bare-metal hardware for production workloads. +- Prepare your domain and DNS settings in advance. +- Ensure you have root or sudo access to the server. +- If you're not ready for bare-metal, try our [Super Quick Start](/docs/tutorials/super-quick-start) on Phala Cloud. + diff --git a/docs/getting-started/install/step-2-update-server.mdx b/docs/getting-started/install/step-2-update-server.mdx new file mode 100644 index 00000000..4b8080e1 --- /dev/null +++ b/docs/getting-started/install/step-2-update-server.mdx @@ -0,0 +1,22 @@ +--- +title: "Step 2: Update Your Server for dstack Installation" +description: "Apply all available updates and security patches to prepare your system for dstack." +--- + + +Update your server so it has the latest kernel, firmware, and libraries. + +## Update Commands + +```bash +sudo apt update && sudo apt upgrade -y +``` + +*This command updates all packages and applies the latest security patches.* + +--- + +#### Recommendation +- Reboot your server if the kernel or major system libraries are updated. + + diff --git a/docs/getting-started/install/step-3-install-required-packages.mdx b/docs/getting-started/install/step-3-install-required-packages.mdx new file mode 100644 index 00000000..37cd7127 --- /dev/null +++ b/docs/getting-started/install/step-3-install-required-packages.mdx @@ -0,0 +1,148 @@ +--- +title: "Step 3 – Install Required Packages for dstack" +description: "Install kernel headers, development tools, Rust, and WireGuard so your host can build and run dstack securely." +--- + +## Why this step matters 🔍 + +dstack compiles kernel-level helpers (via WireGuard) and runs +micro-VMs. +Before it can start, your host **must** have: + +1. **Kernel headers** that exactly match your running kernel (for out-of-tree modules). +2. **Build-essential** tool-chain (gcc, make, etc.). +3. **Rust tool-chain** (dstack, guest helpers, and some plugins are written in Rust). +4. **WireGuard** userspace & kernel module for encrypted overlay networking. + +> **Good to know:** +> These commands assume **Ubuntu 20.04+** (including 24.04). +> For other distros, install the equivalent packages (e.g. `dnf groupinstall "Development Tools"` on Fedora). + +--- + +## Prerequisites + +- A bare-metal **TDX** server set up via [canonical/tdx](https://github.com/canonical/tdx) + (ensures hardware isolation + SGX/TDX firmware support). +- Public **IPv4** address on the machine. +- **16 GB RAM** and **100 GB** free disk (minimum). +- A domain with DNS control if you’ll expose `dstack-gateway` over HTTPS. + +--- + +## 1 – Update the package cache + +Always refresh apt metadata first: + +```bash +sudo apt update +```` + +--- + +## 2 – Install kernel headers, dev tools, and WireGuard + +```bash +sudo apt install -y \ + linux-headers-$(uname -r) \ + build-essential \ + wireguard \ + wireguard-tools \ + chrpath diffstat lz4 xorriso +``` + +* `linux-headers-$(uname -r)` – **must** match `uname -r`; otherwise DKMS fails. +* `build-essential` – gcc, g++, make, libc headers. +* `wireguard` + `wireguard-tools` – encrypted overlay between VM and gateway. +* `chrpath`, `diffstat`, `lz4`, `xorriso` – helpers pulled in by dstack build scripts. + +> 💡 *If you just upgraded your kernel and the exact header package is not yet published, reboot into an older kernel (via GRUB) whose headers exist, or wait until the mirror catches up.* + +--- + +## 3 – Install the Rust tool-chain + +dstack targets **stable** Rust. Use `rustup` so future updates are one command away: + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +# then activate without re-logging: +source $HOME/.cargo/env +rustc --version # sanity check +``` + +--- + +## 4 – Create the dstack environment file + +dstack reads runtime settings from `/etc/dstack/.env`. + +```bash +sudo install -d -m 755 /etc/dstack +sudo tee /etc/dstack/.env >/dev/null <<'EOF' +# /etc/dstack/.env +DSTACK_DOMAIN=example.com # Your public domain (A/AAAA record → server IP) +DSTACK_EMAIL=admin@example.com # Let's Encrypt contact & expiry warnings +DSTACK_API_PORT=9090 # REST / gRPC API +DSTACK_UI_PORT=9080 # Web UI +EOF +sudo chmod 600 /etc/dstack/.env # protect secrets +``` + +**Why these values?** + +| Variable | Reason | +| ------------------------------------ | ---------------------------------------------------------------------------------------------- | +| `DSTACK_DOMAIN` | Enables automatic HTTPS via ACME (Zero-Trust gateway). | +| `DSTACK_EMAIL` | Required by Let’s Encrypt for expiry notices & abuse reports. | +| `DSTACK_API_PORT` / `DSTACK_UI_PORT` | Separate the JSON API from the user-facing UI so you can lock one down via firewall if needed. | + +--- + +## 5 – Register dstack as a `systemd` service + +Running dstack under `systemd` guarantees auto-start on boot and automatic restart on crash. + +```bash +sudo tee /etc/systemd/system/dstack.service >/dev/null <<'EOF' +[Unit] +Description=dstack Runtime +Wants=network-online.target +After=network-online.target + +[Service] +Type=simple +EnvironmentFile=/etc/dstack/.env +ExecStart=/usr/local/bin/dstack run \ + --domain ${DSTACK_DOMAIN} \ + --email ${DSTACK_EMAIL} \ + --api-port ${DSTACK_API_PORT} \ + --ui-port ${DSTACK_UI_PORT} +Restart=on-failure +RestartSec=3 + +[Install] +WantedBy=multi-user.target +EOF + +sudo systemctl daemon-reload +sudo systemctl enable --now dstack +``` + +### Verify + +```bash +systemctl status dstack --no-pager +journalctl -fu dstack +``` + +You should see `Listening on https://` and no errors about WireGuard or TLS. + +--- + +## Next Steps + +1. **Open ports** `80` and `443` (or your custom ports) on any cloud firewall. +2. Proceed to **Step 4 – Deploy dstack UI** to push your first container or notebook. +3. Optionally harden the host (fail2ban, UFW rules, unattended-upgrades). + diff --git a/docs/getting-started/install/step-4-install-dstack-runtime.mdx b/docs/getting-started/install/step-4-install-dstack-runtime.mdx new file mode 100644 index 00000000..7605e2ea --- /dev/null +++ b/docs/getting-started/install/step-4-install-dstack-runtime.mdx @@ -0,0 +1,88 @@ +--- +title: "Step 4 – Build and Run dstack components" +description: "Build the dstack components, start the core services, and verify everything in the UI." +--- + +> **Heads-up:** This step assumes you finished **Step 3** (kernel headers, Rust, WireGuard, `.env`, and the `systemd` unit). + +--- + +## 1 – Clone the Sources + +```bash +git clone https://github.com/Dstack-TEE/meta-dstack.git +cd meta-dstack +```` + +--- + +## 2 – Visual Walk-through + +### 2.1 Connect to Your Server + +| Action | | +| --------------------------- | ----------------------------------------------------------------------------------------- | +| SSH into the host | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step1.png)
[step1.png](/docs/getting-started/first-deployment-steps/step-install-guide/step1.png) | +| Accept the fingerprint | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step2.png)
[step2.png](/docs/getting-started/first-deployment-steps/step-install-guide/step2.png) | +| Confirm WireGuard installed | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step4.0.png)
[step4.0.png](/docs/getting-started/first-deployment-steps/step-install-guide/step4.0.png) | + +--- + +### 2.2 Prepare the Build Environment + +| Action | | +| --------------------------- | ----------------------------------------------------------------------------------------- | +| Install Rust (rustup) | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step4.1.png)
[step4.1.png](/docs/getting-started/first-deployment-steps/step-install-guide/step4.1.png) | +| Finish rustup setup | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step4.2.png)
[step4.2.png](/docs/getting-started/first-deployment-steps/step-install-guide/step4.2.png) | +| Clone **meta-dstack** | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step4.3.png)
[step4.3.png](/docs/getting-started/first-deployment-steps/step-install-guide/step4.3.png) | +| Generate local build config | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step4.4.png)
[step4.4.png](/docs/getting-started/first-deployment-steps/step-install-guide/step4.4.png) | + +--- + +### 2.3 Build dstack Binaries + +Inside the repo: + +```bash +./build.sh hostcfg # host configuration +./build.sh dl # gateway helper +./build.sh guest # guest agent +``` + +| Command | | +| -------------------- | ----------------------------------------------------------------------------------- | +| `./build.sh hostcfg` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step5.png)
[step5.png](/docs/getting-started/first-deployment-steps/step-install-guide/step5.png) | +| `./build.sh dl …` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step6.png)
[step6.png](/docs/getting-started/first-deployment-steps/step-install-guide/step6.png) | +| `./build.sh guest` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step7.png)
[step7.png](/docs/getting-started/first-deployment-steps/step-install-guide/step7.png) | + +--- + +## 3 – Start Core Services + +```bash +# 1. Key-management service +./target/release/dstack-kms --config kms.toml +# 2. Gateway +./target/release/dstack-gateway --config gateway.toml +# 3. Virtual-machine manager +./target/release/dstack-vmm --config vmm.toml +``` + +| Action | | +| ----------------- | -------------------------------------------------------------------------------------------- | +| Start `kms` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step9.png)
[step9.png](/docs/getting-started/first-deployment-steps/step-install-guide/step9.png) | +| Start `gateway` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step10.png)
[step10.png](/docs/getting-started/first-deployment-steps/step-install-guide/step10.png) | +| Start `vmm` | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step11.png)
[step11.png](/docs/getting-started/first-deployment-steps/step-install-guide/step11.png) | +| Open VMM UI | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step12.0.png)
[step12.0.png](/docs/getting-started/first-deployment-steps/step-install-guide/step12.0.png) | +| Verify components | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step12.1.png)
[step12.1.png](/docs/getting-started/first-deployment-steps/step-install-guide/step12.1.png) | +| Ready to deploy | ![](/docs/getting-started/first-deployment-steps/step-install-guide/step12.2.png)
[step12.2.png](/docs/getting-started/first-deployment-steps/step-install-guide/step12.2.png) | + +--- + +## ✅ Next Step: Deploy Your First Application + +By now you've successfully built and started all the core dstack components. Your dstack cluster is now ready to deploy confidential applications. + +To continue with deploying your first application, visit: + +[**dstack Deployment Walkthrough**](/docs/getting-started/deploying-applications) diff --git a/docs/getting-started/start.mdx b/docs/getting-started/start.mdx new file mode 100644 index 00000000..4760076c --- /dev/null +++ b/docs/getting-started/start.mdx @@ -0,0 +1,226 @@ +--- +title: "Start deploying apps with dstack" +description: "Configure your dstack environment and prepare for secure application deployment" +--- + +
+ {/* Header */} +
+ {/* No mascot image here anymore */} +
+ + {/* Deploy an app button with blurred mascot background */} + + +
+ dstack lets you deploy secure containerized apps with hardware-backed protection. if you're new, we recommend starting with the Jupyter Notebook Quick Start. for more details on the repo structure and core components, see github.com/Dstack-TEE/dstack. +
+ + {/* Cards for install and deployment */} +
+ {/* Install card */} + { + e.currentTarget.style.background = '#e0f2fe'; + e.currentTarget.style.border = '1px solid #a7f3d0'; + e.currentTarget.style.boxShadow = '0 2px 8px 0 #a7f3d033, 0 1px 4px 0 rgba(0,0,0,0.08)'; + }} + onMouseOut={e => { + e.currentTarget.style.background = '#f7fee7'; + e.currentTarget.style.border = '1px solid #e0e0e0'; + e.currentTarget.style.boxShadow = '0 1px 4px rgba(0,0,0,0.02)'; + }} + > + ⬇️ +
+ #1 Install dstack +
+
+ Step-by-step install instructions. +
+ + {/* First deployment card */} + { + e.currentTarget.style.background = '#e0f2fe'; + e.currentTarget.style.border = '1px solid #a7f3d0'; + e.currentTarget.style.boxShadow = '0 2px 8px 0 #a7f3d033, 0 1px 4px 0 rgba(0,0,0,0.08)'; + }} + onMouseOut={e => { + e.currentTarget.style.background = '#f7fee7'; + e.currentTarget.style.border = '1px solid #e0e0e0'; + e.currentTarget.style.boxShadow = '0 1px 4px rgba(0,0,0,0.02)'; + }} + > + 🚀 +
+ #2 First Deployment Guide +
+
+ Deploy your first app to a Confidential VM. +
+ +
+ + {/* GitHub repo card */} + +
diff --git a/docs/getting-started/txt.txt b/docs/getting-started/txt.txt new file mode 100644 index 00000000..8af2d61d --- /dev/null +++ b/docs/getting-started/txt.txt @@ -0,0 +1,59 @@ +## 🚦 Launch dstack Infrastructure + +> **warning:** run each step below in a separate terminal window, in order. + +
+ + {/* Step 1: Connect to Remote Machine */} +
+
+ 1 +

Connect to your dstack host

+
+ + ssh <user>@<host> + +

Open a terminal and SSH into your remote dstack host.

+
+ + {/* Step 2: Start Key Management Service */} +
+
+ 2 +

Start key management service (KMS)

+
+ + cd meta-dstack/ + cd build/ + ./dstack-kms -c kms.toml + +

In a new terminal, start the KMS service for secure key management.

+
+ + {/* Step 3: Start Gateway Service */} +
+
+ 3 +

Start gateway service

+
+ + cd meta-dstack/ + cd build/ + sudo ./dstack-gateway -c gateway.toml + +

In another terminal, start the gateway service to handle network routing.

+
+ + {/* Step 4: Start Virtual Machine Manager */} +
+
+ 4 +

Start virtual machine manager (VMM)

+
+ + cd meta-dstack/ + cd build/ + ./dstack-vmm -c vmm.toml + +

In a separate terminal, launch the VMM service to manage your CVMs.

+
\ No newline at end of file diff --git a/docs/images/README.md b/docs/images/README.md new file mode 100644 index 00000000..cbac68e0 --- /dev/null +++ b/docs/images/README.md @@ -0,0 +1,29 @@ +# Documentation Images + +This directory contains images used in the dstack documentation. + +## Placeholder Images + +The following placeholder images are referenced in the documentation: + +- `ecosystem-architecture.png` - dstack ecosystem architecture diagram +- `dashboard-architecture.png` - Web dashboard architecture overview +- `dstack-architecture-detailed.png` - Detailed platform architecture + +These are placeholder references. In a production documentation setup, these would be replaced with actual architectural diagrams, screenshots, and technical illustrations. + +## Adding Real Images + +To add real images: + +1. Create or obtain the appropriate diagrams/screenshots +2. Save them in this directory with the exact filenames referenced in the docs +3. Ensure images are optimized for web (compressed, appropriate resolution) +4. Use descriptive alt text in the documentation for accessibility + +## Image Guidelines + +- **Format**: PNG for diagrams, JPG for photos +- **Resolution**: Maximum 2048px width +- **File size**: Keep under 500KB where possible +- **Naming**: Use lowercase with hyphens, descriptive names \ No newline at end of file diff --git a/docs/images/arm-dillo.png b/docs/images/arm-dillo.png new file mode 100644 index 00000000..0150ffb7 Binary files /dev/null and b/docs/images/arm-dillo.png differ diff --git a/docs/images/before-after-dstack.png b/docs/images/before-after-dstack.png new file mode 100644 index 00000000..7ea9af4c Binary files /dev/null and b/docs/images/before-after-dstack.png differ diff --git a/docs/images/complex-simple-pro.png b/docs/images/complex-simple-pro.png new file mode 100644 index 00000000..af3ee3a8 Binary files /dev/null and b/docs/images/complex-simple-pro.png differ diff --git a/docs/images/create-vm.png b/docs/images/create-vm.png new file mode 100644 index 00000000..7e4690df Binary files /dev/null and b/docs/images/create-vm.png differ diff --git a/docs/images/delpoy-instance-main.png b/docs/images/delpoy-instance-main.png new file mode 100644 index 00000000..db702160 Binary files /dev/null and b/docs/images/delpoy-instance-main.png differ diff --git a/docs/images/deploy-instance-2.png b/docs/images/deploy-instance-2.png new file mode 100644 index 00000000..1b5a7da9 Binary files /dev/null and b/docs/images/deploy-instance-2.png differ diff --git a/docs/images/deploy-instance-3.png b/docs/images/deploy-instance-3.png new file mode 100644 index 00000000..bbf85b9e Binary files /dev/null and b/docs/images/deploy-instance-3.png differ diff --git a/docs/images/deploy-instance-4.png b/docs/images/deploy-instance-4.png new file mode 100644 index 00000000..29ad9a5a Binary files /dev/null and b/docs/images/deploy-instance-4.png differ diff --git a/docs/images/deploy-instance-5.png b/docs/images/deploy-instance-5.png new file mode 100644 index 00000000..586bd9ee Binary files /dev/null and b/docs/images/deploy-instance-5.png differ diff --git a/docs/images/deploy-instance.png b/docs/images/deploy-instance.png new file mode 100644 index 00000000..816e4887 Binary files /dev/null and b/docs/images/deploy-instance.png differ diff --git a/docs/images/deployment-process.png b/docs/images/deployment-process.png new file mode 100644 index 00000000..b2e58a67 Binary files /dev/null and b/docs/images/deployment-process.png differ diff --git a/docs/images/deployment-timelord.png b/docs/images/deployment-timelord.png new file mode 100644 index 00000000..1f382978 Binary files /dev/null and b/docs/images/deployment-timelord.png differ diff --git a/docs/images/deployment-workflow.png b/docs/images/deployment-workflow.png new file mode 100644 index 00000000..55d4136b Binary files /dev/null and b/docs/images/deployment-workflow.png differ diff --git a/docs/images/docker-logo.png b/docs/images/docker-logo.png new file mode 100644 index 00000000..048e3d87 Binary files /dev/null and b/docs/images/docker-logo.png differ diff --git a/docs/images/dstack-architecture-detailed.png b/docs/images/dstack-architecture-detailed.png new file mode 100644 index 00000000..a8cd28d7 Binary files /dev/null and b/docs/images/dstack-architecture-detailed.png differ diff --git a/docs/images/dstack-arcitecture.png b/docs/images/dstack-arcitecture.png new file mode 100644 index 00000000..974f3956 Binary files /dev/null and b/docs/images/dstack-arcitecture.png differ diff --git a/docs/images/dstack-os-diagram.png b/docs/images/dstack-os-diagram.png new file mode 100644 index 00000000..f486856e Binary files /dev/null and b/docs/images/dstack-os-diagram.png differ diff --git a/docs/images/dstack-vmm-pro.png b/docs/images/dstack-vmm-pro.png new file mode 100644 index 00000000..256b97c1 Binary files /dev/null and b/docs/images/dstack-vmm-pro.png differ diff --git a/docs/images/dstack_Banner_pro.png b/docs/images/dstack_Banner_pro.png new file mode 100644 index 00000000..b584b902 Binary files /dev/null and b/docs/images/dstack_Banner_pro.png differ diff --git a/docs/images/dstack_outcomes.png b/docs/images/dstack_outcomes.png new file mode 100644 index 00000000..830e787b Binary files /dev/null and b/docs/images/dstack_outcomes.png differ diff --git a/docs/images/full-deployment-imgs/deployment-guide-tdx-pro.png b/docs/images/full-deployment-imgs/deployment-guide-tdx-pro.png new file mode 100644 index 00000000..4da81187 Binary files /dev/null and b/docs/images/full-deployment-imgs/deployment-guide-tdx-pro.png differ diff --git a/docs/images/how-guest-operates.png b/docs/images/how-guest-operates.png new file mode 100644 index 00000000..0a7eae13 Binary files /dev/null and b/docs/images/how-guest-operates.png differ diff --git a/docs/images/key-derivation.png b/docs/images/key-derivation.png new file mode 100644 index 00000000..b23d8475 Binary files /dev/null and b/docs/images/key-derivation.png differ diff --git a/docs/images/kms-architecture-overview.png b/docs/images/kms-architecture-overview.png new file mode 100644 index 00000000..03145d0b Binary files /dev/null and b/docs/images/kms-architecture-overview.png differ diff --git a/docs/images/kms-governance.png b/docs/images/kms-governance.png new file mode 100644 index 00000000..d9dbb554 Binary files /dev/null and b/docs/images/kms-governance.png differ diff --git a/docs/images/note-book-pro.png b/docs/images/note-book-pro.png new file mode 100644 index 00000000..3cc8cc33 Binary files /dev/null and b/docs/images/note-book-pro.png differ diff --git a/docs/images/phala-logo.png b/docs/images/phala-logo.png new file mode 100644 index 00000000..5083650c Binary files /dev/null and b/docs/images/phala-logo.png differ diff --git a/docs/images/risk-reduction-chart.png b/docs/images/risk-reduction-chart.png new file mode 100644 index 00000000..a5d3362d Binary files /dev/null and b/docs/images/risk-reduction-chart.png differ diff --git a/docs/images/verifiable-compliance-pro.png b/docs/images/verifiable-compliance-pro.png new file mode 100644 index 00000000..932958b3 Binary files /dev/null and b/docs/images/verifiable-compliance-pro.png differ diff --git a/docs/images/vmm internal arch.png b/docs/images/vmm internal arch.png new file mode 100644 index 00000000..a1705821 Binary files /dev/null and b/docs/images/vmm internal arch.png differ diff --git a/docs/images/web2-web3.png b/docs/images/web2-web3.png new file mode 100644 index 00000000..85068b18 Binary files /dev/null and b/docs/images/web2-web3.png differ diff --git a/docs/images/what-tee-provide-pro.png b/docs/images/what-tee-provide-pro.png new file mode 100644 index 00000000..d91c98f7 Binary files /dev/null and b/docs/images/what-tee-provide-pro.png differ diff --git a/docs/images/why-dstack-glance-pro.png b/docs/images/why-dstack-glance-pro.png new file mode 100644 index 00000000..2b7c1013 Binary files /dev/null and b/docs/images/why-dstack-glance-pro.png differ diff --git a/docs/images/zt-tls.png b/docs/images/zt-tls.png new file mode 100644 index 00000000..d910b44c Binary files /dev/null and b/docs/images/zt-tls.png differ diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 00000000..24b05eb9 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,135 @@ +--- +title: "Getting Started" +description: "Easily build and deploy containerized apps to your own confidential virtual machine using the dstack framework" +--- + +## Begin by deploying your first dstack app + + + +## Zero Code Changes, Maximum Security, and Full Control + +
+
+

+ + + + Use Your Existing Code +

+

Drop in your existing Docker containers—dstack works as-is. No rewrites, no SDKs, just instant TEE.

+
+
+

+ + + + Protected Programming +

+

Get hardware-enforced, zero-trust compute. Security is built in, not bolted on.

+
+
+

+ + + + No Vendor Lock-in +

+

Bare metal, cloud, or hybrid—deploy anywhere. Hardware abstraction enables full deployment flexibility.

+
+
+ +--- + +## Dive Deeper + +
+ +

Understand TEE, attestation, and our architecture

+ + + + +

Step-by-step guides for common use cases

+ + + + +

Connect, share, and collaborate with other dstack users

+ + + + +

Explore security model, research, and advanced topics

+ + +
diff --git a/docs/overview/benefits.mdx b/docs/overview/benefits.mdx new file mode 100644 index 00000000..c163a898 --- /dev/null +++ b/docs/overview/benefits.mdx @@ -0,0 +1,99 @@ +--- +title: "Value Add" +description: "How dstack shrinks security risk, audit toil, and time‑to‑market—without changing your workflow." +--- + +# Launch a Confidential Cloud—fast + +dstack turns any Docker‑Compose stack into a hardware‑sealed, cryptographically attested enclave that runs on public clouds, bare metal, or under smart‑contract control. The result: stronger security, smoother audits, and room to innovate—all with the tools you already use. + +
+ Why dstack? At a glance +
+ +
+ Verifiable compliance UI +
+ +--- + +## Operational Upside + +- **Zero‑change deployment:** ship the containers you have; dstack adds the enclave layer at runtime. +- **Self‑healing scale:** auto‑repairs and auto‑scales without leaking state. +- **Leak‑free observability:** real‑time metrics and logs stay inside the TEE boundary. +- **Click‑to‑manage UI:** pause, resume, or revoke workloads without touching the CLI. + +
+ Fast security deployment with dstack +
+ +## Security & Compliance at the Core + +- **Hardware‑enforced isolation** blocks kernel, hypervisor, and insider attacks. +- **Cryptographic attestation** proves code, config, and firmware on every boot. +- **Always‑on encryption** protects data in use, at rest, and in transit. +- **One‑click compliance** surfaces SOC 2, GDPR, and HIPAA evidence instantly. + +
+ Risk reduction with dstack +
+ + +--- + +## Meta + +**Use SDKs in any language**—connect your app to secure enclaves without changing your code. + +**All internal traffic is encrypted and authenticated**—your cloud apps are protected by default. + +**Enclaves auto-scale and self-heal**—your services stay online, even if something fails. + +**See real-time metrics and logs**—debug easily, but sensitive data never leaks. + +**Encryption and security checks run at hardware speed**—big data and AI stay fast. + +**Every admin action and key event is logged and tamper-proof**—compliance and audits are simple. + +**Compliance checks and reports are automated**—meet standards like GDPR or SOC 2 with no extra work. + +**Only verified containers go to production enclaves**—supply-chain attacks are blocked before they start. + +--- + +## A new way to take control over your programs + +- **On‑chain key custody** replaces central vaults with distributed trust. +- **Supply‑chain shield** blocks unverified images before prod. +- **Faster deal cycles:** attested proofs turn weeks of security reviews into minutes. +- **Premium services:** monetize confidential AI, finance, or healthcare workloads without exposing IP or data. + +> **Bottom line:** dstack delivers secure, scalable, and compliant cloud deployments—no rewrites, no slowdowns. + +--- + +## Get Started + +- **Install :** [`/docs/getting-started/installation`](/docs/getting-started/install/installation.mdx) +- **Tutorials :** [`/docs/tutorials`](/docs/tutorials/index-quick-start) diff --git a/docs/overview/case-studies.mdx b/docs/overview/case-studies.mdx new file mode 100644 index 00000000..1e36ab99 --- /dev/null +++ b/docs/overview/case-studies.mdx @@ -0,0 +1,333 @@ +--- +title: "Case Studies" +description: "Real-world implementations and success stories of organizations using dstack" +--- + + +This collection of case studies demonstrates the transformative impact of dstack across various industries and use cases. Each study provides detailed insights into implementation challenges, architectural decisions, and measurable outcomes. These real-world examples serve as both validation of dstack's capabilities and practical guides for organizations considering similar deployments. + + +The transition from theoretical benefits to practical implementation often presents unexpected challenges and opportunities. These case studies document the journeys of organizations that have successfully deployed dstack in production environments, offering valuable lessons learned and best practices. From financial institutions processing sensitive transactions to healthcare organizations enabling secure multi-institutional research, these examples illustrate the versatility and robustness of the dstack platform. + +Each case study follows a structured format that examines the initial challenges, solution architecture, implementation process, and quantifiable results. This systematic approach enables readers to extract applicable insights for their own deployments while understanding the specific context that shaped each implementation. + + +## Featured Case Studies + +### 1. Global Financial Services: Secure Multi-Party Risk Analysis + +
+

Organization: Meridian Financial Group

+

Industry: Banking & Financial Services | Deployment Size: 500+ Applications

+
+ +#### Challenge + +Meridian Financial Group needed to perform risk analysis across multiple subsidiary banks without exposing individual customer data or proprietary risk models. Traditional approaches required data centralization, creating regulatory compliance issues and competitive concerns. + +#### Solution Architecture + + +The organization deployed dstack to create a secure multi-party computation environment where each subsidiary could contribute to risk calculations without revealing underlying data. The architecture leveraged dstack's hardware-enforced isolation to ensure that even system administrators couldn't access sensitive information during processing. + + +```mermaid +graph TB + subgraph "Subsidiary Banks" + A[Bank A Data] + B[Bank B Data] + C[Bank C Data] + end + + subgraph "dstack Platform" + D[Secure Ingestion] + E[Risk Computation CVM] + F[Aggregated Results] + end + + subgraph "Outputs" + G[Regulatory Reports] + H[Risk Dashboard] + end + + A -->|Encrypted| D + B -->|Encrypted| D + C -->|Encrypted| D + D --> E + E --> F + F --> G + F --> H + + style E fill:#e3f2fd +``` + +#### Implementation Timeline + +- **Week 1-2**: Proof of concept with synthetic data +- **Week 3-4**: Integration with existing data pipelines +- **Week 5-8**: Security audit and compliance verification +- **Week 9-12**: Phased production rollout +- **Week 13+**: Full production deployment + +#### Results + +| Metric | Before dstack | After dstack | Improvement | +|--------|--------------|--------------|-------------| +| Risk Analysis Time | 5 days | 4 hours | 96% faster | +| Data Exposure Risk | High | Zero | 100% reduction | +| Regulatory Compliance | Manual audits | Automated proof | 80% cost reduction | +| Cross-subsidiary Insights | Limited | Comprehensive | 10x increase | + +#### Key Learnings + + +The ability to provide cryptographic proof of data protection transformed regulatory conversations from lengthy reviews to straightforward verification processes. + + +### 2. Healthcare Consortium: Federated Clinical Research + +
+

Organization: United Health Research Network

+

Industry: Healthcare & Life Sciences | Deployment Size: 12 Institutions

+
+ +#### Challenge + +Twelve leading medical institutions wanted to collaborate on rare disease research but couldn't share patient data due to HIPAA regulations and institutional policies. Traditional de-identification methods reduced data utility and still posed re-identification risks. + +#### Solution Architecture + + +dstack enabled a federated learning environment where machine learning models could be trained across distributed datasets without any data movement. Each institution maintained complete control over their data while contributing to collective insights. + + +#### Implementation Details + +```python +# Federated Training Orchestration +class FederatedResearch: + def __init__(self, institutions): + self.institutions = institutions + self.dstack_client = DstackClient() + + def train_model(self, model_config): + # Deploy secure training environment + training_cvm = self.dstack_client.deploy_cvm( + image="federated-ml:latest", + attestation_policy=HealthcarePolicy() + ) + + # Each institution contributes without data exposure + for institution in self.institutions: + local_update = training_cvm.secure_compute( + function=train_local_model, + data_ref=institution.data_reference, + current_weights=self.global_weights + ) + + # Aggregate updates using secure aggregation + self.global_weights = self.secure_aggregate( + local_update, + self.global_weights + ) + + return self.global_weights +``` + +#### Outcomes + +- **Research Acceleration**: Reduced time to insights from years to months +- **Data Utilization**: 100% of patient data usable (vs. 30% with de-identification) +- **Compliance**: Full HIPAA compliance with automated audit trails +- **Publications**: 3 breakthrough papers in first year +- **Patient Impact**: Identified novel treatment pathways for 4 rare diseases + +### 3. Technology Startup: Confidential AI Services + +
+

Organization: NeuralVault AI

+

Industry: Artificial Intelligence | Deployment Size: SaaS Platform

+
+ +#### Challenge + +NeuralVault developed proprietary AI models for financial forecasting but couldn't deploy them to cloud infrastructure without risking intellectual property theft. Traditional approaches like obfuscation provided insufficient protection for their competitive advantage. + +#### Solution Architecture + + +Using dstack, NeuralVault created a secure inference platform where clients could use AI models without the models ever being exposed. The platform leveraged TEE attestation to prove model integrity while keeping weights and architecture confidential. + + +#### Business Impact + +- **Revenue Growth**: 300% increase in enterprise clients +- **IP Protection**: Zero model leakage incidents +- **Client Trust**: 95% conversion rate after security demonstration +- **Competitive Advantage**: First-to-market with verifiable AI security + +### 4. Government Agency: Secure Inter-Department Analytics + +
+

Organization: National Statistics Bureau

+

Industry: Government | Deployment Size: 15 Departments

+
+ +#### Challenge + +Multiple government departments needed to perform joint analytics for policy decisions but couldn't share citizen data due to privacy laws and inter-departmental data governance policies. + +#### Implementation Approach + +1. **Pilot Phase**: Started with non-sensitive datasets to build confidence +2. **Governance Framework**: Established cross-department data sharing agreements +3. **Technical Deployment**: Rolled out dstack incrementally across departments +4. **Training Program**: Educated 200+ analysts on secure analytics practices + +#### Quantified Benefits + +
+
+
Efficiency Gains
+
    +
  • • Policy analysis time: -70%
    • +
  • • Data preparation: -85%
    • +
  • • Report generation: -60%
    • +
+
+
+
Quality Improvements
+
    +
  • • Data coverage: +250%
    • +
  • • Analysis accuracy: +40%
    • +
  • • Citizen privacy: 100% preserved
    • +
+
+
+ +### 5. Pharmaceutical Research: Drug Discovery Collaboration + +
+

Organization: Global Pharma Alliance

+

Industry: Pharmaceutical | Deployment Size: 8 Companies

+
+ +#### Challenge + +Competing pharmaceutical companies wanted to collaborate on early-stage drug discovery to reduce duplicate research efforts, but couldn't share proprietary compound libraries or research data. + +#### Innovative Solution + + +dstack enabled a "competitive collaboration" model where companies could identify overlapping research areas and potential synergies without revealing specific intellectual property. The platform used secure multi-party computation to find statistical patterns across encrypted datasets. + + +#### Impact Metrics + +- **Research Efficiency**: 40% reduction in duplicate efforts +- **Cost Savings**: $2.3B collective savings in first 18 months +- **Time to Market**: 18-month average acceleration for joint projects +- **New Discoveries**: 12 novel drug candidates identified through collaboration + +## Common Success Factors + + +Analyzing these case studies reveals several common factors that contributed to successful dstack deployments: + + +### 1. Executive Sponsorship +All successful deployments had strong executive support that viewed confidential computing as a strategic enabler rather than just a security measure. + +### 2. Phased Approach +Organizations that started with pilot projects and gradually expanded showed better outcomes than those attempting large-scale immediate deployments. + +### 3. Cross-Functional Teams +Success required collaboration between security, development, operations, and business teams from the project's inception. + +### 4. Clear Value Metrics +Organizations that defined specific, measurable objectives achieved better ROI and stakeholder buy-in. + +### 5. Continuous Learning +The most successful deployments treated implementation as a learning process, continuously refining their approach based on operational feedback. + +## Lessons Learned + + +These real-world implementations provide valuable insights for organizations planning their own dstack deployments. + + +### Technical Lessons + +1. **Start Simple**: Begin with straightforward use cases before tackling complex multi-party scenarios +2. **Performance Planning**: Account for TEE overhead in capacity planning from the start +3. **Monitoring Strategy**: Implement comprehensive monitoring that respects confidentiality boundaries +4. **Backup Architecture**: Design for resilience with proper backup and recovery procedures + +### Organizational Lessons + +1. **Change Management**: Invest heavily in training and communication to overcome resistance +2. **Governance First**: Establish data governance frameworks before technical implementation +3. **Security Culture**: Use dstack deployment as an opportunity to enhance overall security awareness +4. **Iterative Improvement**: Plan for continuous optimization based on operational experience + +## Industry-Specific Insights + +### Financial Services +- Focus on regulatory compliance automation +- Emphasize auditability and transparency +- Design for high-frequency, low-latency operations + +### Healthcare +- Prioritize patient privacy above all else +- Build trust through incremental successes +- Leverage federated learning capabilities + +### Government +- Navigate complex procurement processes early +- Ensure solution meets sovereignty requirements +- Plan for long-term sustainability + +### Technology +- Use dstack as a competitive differentiator +- Focus on protecting intellectual property +- Design for global scale from the start + +## Getting Started with Your Implementation + + +These case studies demonstrate that successful dstack deployment is not just about technology—it's about aligning technical capabilities with business objectives and organizational culture. Whether you're a financial institution seeking secure analytics, a healthcare organization enabling research collaboration, or a technology company protecting intellectual property, these real-world examples provide a roadmap for success. + + +## Next Steps + +Ready to create your own success story with dstack? + + + +
+

Share Your Story

+

+ Have you successfully deployed dstack in your organization? We'd love to feature your story in our case studies. Contact us at casestudies@dstack.dev to share your experience and help others learn from your journey. +

+
+ + +## Example Use Cases + +- You can run analytics on private medical or financial data, without exposing it to anyone. +- You can train or serve AI/ML models while keeping both the model and the data confidential. +- You can set up joint computations with other organizations, with each party’s data remaining private. +- You can easily demonstrate to auditors or partners that your application is running securely, using cryptographic proof. diff --git a/docs/overview/faq..txt.mdx b/docs/overview/faq..txt.mdx new file mode 100644 index 00000000..50663e88 --- /dev/null +++ b/docs/overview/faq..txt.mdx @@ -0,0 +1,704 @@ +--- +title: "Frequently Asked Questions" +description: "Comprehensive answers to common questions about dstack, covering everything from basic concepts to advanced deployment scenarios." +--- + +# dstack FAQ + +this comprehensive FAQ addresses the most common questions about dstack, from basic concepts to advanced deployment scenarios. if you can't find what you're looking for, check our [troubleshooting guide](/docs/troubleshooting), visit our [community](/docs/community), or explore the [dstack wiki](https://deepwiki.com/Dstack-TEE/dstack/1-introduction-to-dstack) for in-depth AI explanations and further exploration of any topic. + +--- + +## Basic Understanding + +### What exactly is dstack and how is it different from regular Docker? + +dstack is a platform that takes your existing Docker containers and runs them inside **Confidential Virtual Machines (CVMs)** powered by hardware Trusted Execution Environments (TEEs) like Intel TDX. While regular Docker containers share the host OS kernel and can be inspected by system administrators, dstack containers run in hardware-encrypted memory that even the cloud provider cannot access. + +**Key differences:** +- **Regular Docker:** Containers share host OS, visible to system admins, no hardware protection +- **dstack:** Each container runs in its own encrypted VM, protected by hardware TEE, cryptographically verifiable security + +You still use the same `docker-compose.yml` files and Docker images—dstack just adds a secure layer underneath. + +### Do I need to rewrite my application to use dstack? + +**No.** dstack is designed to work with existing containerized applications with minimal to no code changes. You can: + +- Use your existing `Dockerfile` and `docker-compose.yml` files +- Keep your current development workflow +- Deploy the same container images you use today + +The main differences are: +- **Secrets management:** Instead of environment variables, you can use dstack's secure key derivation APIs +- **Networking:** Applications are automatically accessible via HTTPS with certificates managed by dstack +- **Storage:** Persistent data is automatically encrypted using full disk encryption + +### What are Trusted Execution Environments (TEEs) and why do I need them? + +TEEs are specialized hardware features in modern CPUs that create **hardware-encrypted secure enclaves**. Think of them as "black boxes" that: + +- **Encrypt all memory and CPU state** so external observers (including cloud providers) cannot read your data +- **Provide cryptographic proof** that your code is running unmodified via "remote attestation" +- **Isolate your application** from the host operating system and hypervisor + +**Why you need them:** +- **Compliance:** Meet regulatory requirements for data protection (GDPR, HIPAA, etc.) +- **Zero-trust cloud:** Run sensitive workloads on untrusted infrastructure +- **Verifiable security:** Cryptographically prove your application hasn't been tampered with + +### How does dstack compare to other confidential computing solutions? + +| Feature | dstack | Azure Confidential Computing | AWS Nitro Enclaves | Google Confidential GKE | +|---------|---------|------------------------------|-------------------|--------------------------| +| **Container Support** | ✅ Docker Compose | ✅ Limited | ❌ Custom format | ✅ Kubernetes only | +| **Hardware Agnostic** | ✅ Intel TDX + roadmap | ❌ Azure only | ❌ AWS only | ❌ Google only | +| **Open Source** | ✅ Fully open | ❌ Proprietary | ❌ Proprietary | ❌ Proprietary | +| **Decentralized Keys** | ✅ Blockchain KMS | ❌ Cloud provider | ❌ Cloud provider | ❌ Cloud provider | +| **Developer Experience** | ✅ Standard Docker | ⚠️ Modified workflow | ❌ Complex setup | ⚠️ Kubernetes required | + +--- + +## Hardware & Infrastructure + +### What hardware do I need to run dstack? + +**For Development/Testing:** +- Use [Phala Cloud](https://cloud.phala.network/register?invite=beta) - no hardware required +- Get started in 2-3 minutes with click-to-deploy + +**For Self-Hosting:** +- **CPU:** Intel processor with TDX support (4th Gen Xeon Scalable or newer) +- **Memory:** Minimum 16GB RAM, recommended 32GB+ for production +- **Storage:** 100GB+ SSD for the host, additional storage for applications +- **OS:** Ubuntu 24.04 (other distributions on roadmap) + +**Future Hardware Support:** +- AMD SEV-SNP (in development) +- ARM TrustZone/CCA (planned) +- NVIDIA H100 with confidential computing (planned) + +### How can I test dstack without TEE hardware? + +**Option 1: Phala Cloud (Recommended)** +- Sign up at [Phala Cloud](https://cloud.phala.network/register?invite=beta) +- Deploy applications in minutes using real TEE hardware +- Pay-per-use pricing, no upfront costs +- Full dstack feature set available + +**Option 2: Simulation Mode** +- Limited functionality for development +- Cannot provide real attestation or hardware security +- Good for testing application containerization + +**Option 3: Cloud Providers** +- Rent TDX-capable servers from providers like: + - Azure DCsv3/ECsv5 series + - Bare metal providers with latest Xeon processors + +### Is dstack production-ready? + +**Yes, for many use cases.** dstack is actively used in production environments, particularly through Phala Cloud. However, consider these factors: + +**Production-Ready:** +- ✅ Core security features (attestation, encryption, key management) +- ✅ Container orchestration and lifecycle management +- ✅ Automatic HTTPS and certificate management +- ✅ High availability and clustering support +- ✅ Enterprise deployments in financial services and healthcare + +**Consider Carefully:** +- ⚠️ Hardware ecosystem still maturing (Intel TDX is relatively new) +- ⚠️ Limited debugging tools compared to traditional containers +- ⚠️ Performance overhead (10-30% typical for memory-intensive workloads) +- ⚠️ Some advanced Docker features not yet supported + +--- + +## Architecture & Components + +### How do all the dstack components work together? + +dstack uses a **layered architecture** with components that handle different aspects of secure deployment: + +``` +[User] → [dstack CLI] → [dstack-vmm] → [Confidential VM] + ↓ ↓ +[External Traffic] → [dstack-gateway] → [dstack-guest-agent] → [Your App] + ↓ ↓ + [Certificate Mgmt] → [dstack-kms] → [Blockchain] +``` + +**Flow explanation:** +1. **You deploy** using standard `docker-compose.yml` via CLI or web UI +2. **dstack-vmm** creates a new Confidential VM with encrypted memory +3. **dstack-os** boots inside the CVM with minimal attack surface +4. **dstack-guest-agent** starts your containers and manages secrets +5. **dstack-gateway** handles external traffic with automatic HTTPS +6. **dstack-kms** provides encryption keys after verifying CVM integrity +7. **Blockchain contracts** authorize deployments based on code measurements + +### What's the difference between VMM, Gateway, and KMS? + +**dstack-vmm (Virtual Machine Manager):** +- **Role:** Orchestrates CVM lifecycle (create, start, stop, remove) +- **Think of it as:** The "conductor" that manages your secure VMs +- **Key features:** Resource allocation, CVM monitoring, web interface +- **Runs on:** Host machine (outside the secure environment) + +**dstack-gateway (Network Gateway):** +- **Role:** Secure reverse proxy handling external traffic +- **Think of it as:** The "bouncer" that controls access to your applications +- **Key features:** TLS termination, domain routing, certificate management, WireGuard VPN +- **Runs on:** Host machine or dedicated gateway servers + +**dstack-kms (Key Management Service):** +- **Role:** Cryptographic key generation and secret management +- **Think of it as:** The "vault" that controls access to encryption keys +- **Key features:** Remote attestation, key derivation, blockchain integration +- **Runs in:** Its own Confidential VM for maximum security + +### Why does dstack need blockchain integration? + +The blockchain integration solves critical problems with traditional key management: + +**Problems with Centralized KMS:** +- **Vendor lock-in:** Keys tied to specific cloud provider +- **Single point of failure:** If KMS provider goes down, you lose access +- **Trust issues:** Must trust the KMS provider not to access your keys +- **Limited portability:** Hard to move applications between providers + +**dstack's Blockchain Solution:** +- **Decentralized control:** No single entity controls your keys +- **Transparent governance:** All key policies recorded on-chain +- **Hardware portability:** Move applications between TEE providers +- **Cryptographic authorization:** Smart contracts verify code integrity before releasing keys + +**Simple example:** When you deploy an app, its code hash is recorded on-chain. Only CVMs running that exact code can retrieve the encryption keys—preventing unauthorized access even if someone compromises the infrastructure. + +--- + +## Security Model + +### How does remote attestation actually work? + +Remote attestation is like a **cryptographic passport** for your application that proves it's running unmodified in a genuine TEE: + +**Step-by-step process:** +1. **Boot measurement:** TEE hardware measures each component as it loads (bootloader, OS, application) +2. **Quote generation:** Hardware creates a signed "quote" containing these measurements +3. **Quote verification:** External parties can verify the quote using the TEE manufacturer's certificates +4. **Policy check:** Smart contracts compare measurements against approved code hashes +5. **Key release:** If everything matches, encryption keys are provided to the application + +**What gets measured:** +- Bootloader and kernel hashes +- Operating system image +- Application container images +- Configuration files and compose specifications + +**Verification tools:** +- Use the [TEE Attestation Explorer](https://ra-quote-explorer.vercel.app/) to inspect quotes +- Blockchain explorer to verify on-chain policies +- dstack APIs to retrieve current attestation status + +### What threats does dstack protect against? + +**✅ Protected Against:** +- **Malicious cloud providers:** Can't access your encrypted memory or storage +- **Insider threats:** System administrators can't inspect running applications +- **Infrastructure compromises:** Hypervisor or host OS compromises don't affect CVMs +- **Data exfiltration:** All data encrypted at rest and in transit +- **Code tampering:** Remote attestation detects any modifications +- **Man-in-the-middle attacks:** RA-TLS prevents certificate substitution +- **Supply chain attacks:** Only verified code can access encryption keys + +**❌ Not Protected Against:** +- **Application vulnerabilities:** Bugs in your code still exist +- **Side-channel attacks:** Advanced cryptographic attacks (though TEEs have mitigations) +- **Physical hardware attacks:** Direct hardware tampering with advanced tools +- **Social engineering:** Compromising developer accounts or code repositories +- **DDoS attacks:** Application availability depends on network protection + +### How do I verify my application is actually secure? + +dstack provides multiple verification mechanisms: + +**Real-time verification:** +```bash +# Get current attestation quote +curl --unix-socket /var/run/dstack.sock -X POST http://dstack/GetQuote + +# Verify quote using external tools +# Upload to https://ra-quote-explorer.vercel.app/ +``` + +**Blockchain verification:** +- Check your app's registration in KmsAuth contract +- Verify code hashes match your deployment +- Confirm key access policies are correct + +**Continuous monitoring:** +- Monitor certificate transparency logs for unauthorized certificates +- Set up alerts for deployment changes +- Use dstack APIs to track CVM health and status + +**Third-party audits:** +- dstack undergoes regular security audits +- TEE hardware (Intel TDX) is independently certified +- Open source codebase allows community security review + +--- + +## Development & Deployment + +### How do I migrate my existing application to dstack? + +**Phase 1: Assessment (1-2 days)** +```bash +# Check if your app is already containerized +docker-compose -f your-app/docker-compose.yml config + +# Identify external dependencies +# - Databases, APIs, file storage +# - Network requirements +# - Compliance requirements +``` + +**Phase 2: Containerization (if needed)** +```dockerfile +# Ensure your Dockerfile follows best practices +FROM node:18-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY . . +EXPOSE 8080 +CMD ["npm", "start"] +``` + +**Phase 3: dstack Deployment** +```bash +# Deploy to Phala Cloud for testing +# Upload your docker-compose.yml via web interface + +# Or deploy to your own infrastructure +dstack deploy -f docker-compose.yml +``` + +**Phase 4: Security Integration** +```javascript +// Optional: Use dstack APIs for enhanced security +const { DstackClient } = require('@phala/dstack-sdk'); +const client = new DstackClient(); + +// Derive encryption keys instead of environment variables +const appKey = await client.getKey('encryption-key'); +``` + +### Can I use my existing CI/CD pipeline? + +**Yes!** dstack integrates with standard CI/CD workflows: + +**GitHub Actions Example:** +```yaml +name: Deploy to dstack +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Deploy to dstack + run: | + # Option 1: Deploy to Phala Cloud via API + curl -X POST https://api.phala.cloud/deploy \ + -H "Authorization: Bearer ${{ secrets.PHALA_TOKEN }}" \ + -F "compose=@docker-compose.yml" + + # Option 2: Deploy to self-hosted + dstack deploy -f docker-compose.yml \ + --endpoint ${{ secrets.DSTACK_ENDPOINT }} +``` + +**GitLab CI Example:** +```yaml +deploy: + stage: deploy + script: + - dstack deploy -f docker-compose.yml + only: + - main +``` + +**Jenkins Pipeline:** +```groovy +pipeline { + agent any + stages { + stage('Deploy') { + steps { + sh 'dstack deploy -f docker-compose.yml' + } + } + } +} +``` + +### How do I handle secrets and environment variables? + +**Traditional approach (still works):** +```yaml +# docker-compose.yml +services: + app: + image: myapp + environment: + - DATABASE_URL=${DATABASE_URL} + - API_KEY=${API_KEY} +``` + +**Enhanced dstack approach:** +```javascript +// Use dstack SDK for derived keys +const client = new DstackClient(); + +// Derive deterministic keys from app measurement +const databaseKey = await client.getKey('database-encryption'); +const apiKey = await client.getKey('external-api-auth'); + +// Keys are unique per application and can't be accessed by other apps +``` + +**Hybrid approach:** +```yaml +# docker-compose.yml - public config +services: + app: + image: myapp + environment: + - PUBLIC_API_URL=https://api.example.com + - LOG_LEVEL=info + # Secrets retrieved via dstack SDK at runtime +``` + +### What's the performance impact of running in dstack? + +**Typical performance characteristics:** + +| Workload Type | Performance Impact | Notes | +|---------------|-------------------|-------| +| **CPU-intensive** | 5-15% overhead | Cryptographic operations, context switches | +| **Memory-intensive** | 10-30% overhead | Memory encryption/decryption | +| **Network I/O** | 5-10% overhead | TLS termination, VPN overhead | +| **Disk I/O** | 15-25% overhead | Full disk encryption (LUKS) | +| **Database** | 10-20% overhead | Combination of memory and disk overhead | + +**Optimization strategies:** +```bash +# Use more CPU cores to offset encryption overhead +# In vmm.toml +max_allocable_vcpu = 8 + +# Allocate more memory for caching +max_allocable_memory_in_mb = 16384 + +# Use SSD storage for better encrypted I/O performance +``` + +**Benchmarking your app:** +```bash +# Test locally first +docker run --name benchmark myapp +ab -n 10000 -c 100 http://localhost:8080/ + +# Then test in dstack +dstack deploy -f docker-compose.yml +ab -n 10000 -c 100 https://myapp.your-domain.com/ +``` + +--- + +## Operations & Management + +### How do I monitor and debug applications in dstack? + +**Built-in monitoring:** +```bash +# Web interface +open http://localhost:9080 + +# API access to logs +curl 'http://myapp.app.yourdomain.com:9090/logs/?follow=true×tamps=true' + +# Health checks +curl http://localhost:9080/health +``` + +**Application monitoring:** +```yaml +# docker-compose.yml +services: + app: + image: myapp + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/health"] + interval: 30s + timeout: 10s + retries: 3 +``` + +**External monitoring integration:** +```bash +# Prometheus metrics +curl http://localhost:9091/metrics + +# Custom application metrics +# Expose metrics endpoint in your app +# dstack automatically includes it in monitoring +``` + +**Debugging limitations:** +- ❌ Cannot use `docker exec` to shell into CVMs +- ❌ Cannot attach debuggers directly to processes +- ❌ Limited visibility into system internals +- ✅ Can view application logs and metrics +- ✅ Can use remote debugging protocols (if exposed) +- ✅ Can deploy debug versions with additional logging + +### How do I handle application updates and rollbacks? + +**Blue-green deployments:** +```bash +# Deploy new version +dstack deploy -f docker-compose-v2.yml --app-id myapp-v2 + +# Test new version +curl https://myapp-v2.yourdomain.com/health + +# Switch traffic (update DNS or load balancer) +# Remove old version +dstack remove myapp-v1 +``` + +**Rolling updates:** +```yaml +# Use multiple instances for zero-downtime updates +# docker-compose.yml +services: + app: + image: myapp:v2 + deploy: + replicas: 3 + update_config: + parallelism: 1 + delay: 30s +``` + +**Rollback strategy:** +```bash +# Keep previous version images +docker tag myapp:latest myapp:backup + +# Quick rollback +dstack deploy -f docker-compose-backup.yml +``` + +### How do I scale dstack applications? + +**Vertical scaling (single CVM):** +```toml +# vmm.toml +[cvm] +max_allocable_vcpu = 16 +max_allocable_memory_in_mb = 32768 +max_disk_size = 1000 +``` + +**Horizontal scaling (multiple CVMs):** +```bash +# Deploy multiple instances +dstack deploy -f docker-compose.yml --replicas 3 + +# Use load balancer or gateway routing +# Traffic automatically distributed across instances +``` + +**Auto-scaling considerations:** +- CVMs take 30-60 seconds to boot (vs milliseconds for containers) +- Each CVM requires attestation before receiving keys +- Consider keeping warm instances for faster scaling + +**Resource monitoring:** +```bash +# Monitor resource usage +curl http://localhost:9080/api/vms/stats + +# Set up alerts for high resource usage +# Scale proactively based on metrics +``` + +--- + +## Costs & Economics + +### What does it cost to run dstack? + +dstack can be run as a managed service or on your own infrastructure. Costs depend on your deployment model, resource usage, and operational needs. + +**Managed Service:** +- **Pay-per-use:** You are billed only for the resources (such as CVMs) you actively use. +- **No upfront hardware costs:** All infrastructure is provided. +- **Included services:** Automatic updates, monitoring, and support are typically bundled. + +**Self-hosted Infrastructure:** +- **Hardware investment:** Requires servers with TEE support, networking equipment, and storage. +- **Operational costs:** Ongoing expenses include electricity, internet, and maintenance. +- **Full control:** You manage updates, monitoring, and support. + +**Cost comparison:** +- Managed service is generally billed based on actual usage, with no upfront hardware investment. +- Self-hosted deployments require an initial hardware purchase and ongoing operational costs. +- Traditional cloud deployments may be less expensive, but do not provide confidential computing or TEE security. + +**Cost optimization tips:** +- Choose CVM sizes appropriate to your workload. +- Use auto-scaling to match demand. +- Optimize container images for faster boot and lower resource usage. +- Consider using managed services for development and self-hosting for production, or vice versa, depending on your needs. + +### Is dstack more expensive than traditional deployment? + +**Short answer:** Slightly more expensive, but the security benefits often justify the cost. + +**Detailed comparison:** + +| Deployment Model | Monthly Cost (small app) | Security Level | Compliance | +|------------------|-------------------------|----------------|------------| +| **Shared hosting** | $5-20 | ⭐ Low | ❌ Limited | +| **VPS/Cloud VM** | $20-100 | ⭐⭐ Medium | ⚠️ Depends | +| **Traditional containers** | $50-200 | ⭐⭐ Medium | ⚠️ Depends | +| **dstack (Phala Cloud)** | $30-150 | ⭐⭐⭐⭐⭐ Very High | ✅ Built-in | +| **Self-hosted dstack** | $100-500 | ⭐⭐⭐⭐⭐ Very High | ✅ Built-in | + +**When dstack saves money:** +- **Compliance costs:** Avoid expensive audits and certifications +- **Security incidents:** Prevent costly data breaches +- **Vendor lock-in:** Avoid migration costs between cloud providers +- **Development time:** Reduce time spent on security infrastructure + +--- + + +## Troubleshooting + +for a comprehensive guide to diagnosing and fixing common issues, see the [troubleshooting section](/docs/troubleshooting.mdx). it covers error messages, deployment failures, networking problems, and advanced debugging tips specific to dstack. start there if you run into problems, or use the quick tips below for fast checks. + +### My application won't start in dstack. What should I check? + +**Common issues and solutions:** + +**1. Container startup failures:** +```bash +# Check logs +curl 'http://myapp.yourdomain.com:9090/logs/' + +# Common fixes: +# - Ensure your app binds to 0.0.0.0, not localhost +# - Check port mappings in docker-compose.yml +# - Verify image works locally first +``` + +**2. Network connectivity issues:** +```yaml +# docker-compose.yml +services: + app: + ports: + - "8080:8080" # Make sure this matches your app's port + environment: + - HOST=0.0.0.0 # Bind to all interfaces, not just localhost +``` + +**3. Memory or resource issues:** +```bash +# Check resource allocation +curl http://localhost:9080/api/vms/stats + +# Increase resources in vmm.toml +max_allocable_memory_in_mb = 8192 +max_allocable_vcpu = 4 +``` + +**4. Attestation failures:** +```bash +# Check KMS connectivity +curl --cert client.crt --key client.key https://kms:8000/health + +# Verify app is registered in blockchain +# Check measurements match expected values +``` + +### How do I get help when things go wrong? + +**Self-service resources:** +1. **Documentation:** Check [dstack docs](https://docs.dstack.dev) for detailed guides +2. **Troubleshooting guide:** See [troubleshooting](/docs/troubleshooting) for common issues +3. **Community forum:** Search existing discussions and ask questions +4. **GitHub issues:** Check [known issues](https://github.com/Dstack-TEE/dstack/issues) and report bugs + +**Getting support:** +```bash +# Collect diagnostic information +dstack-util show # System measurements +curl http://localhost:9080/health # Component health +curl 'http://myapp:9090/logs/?timestamps=true' # Application logs + +# Include this information when asking for help +``` + +**Phala Cloud users:** +- Built-in support ticket system +- Community Discord for real-time help +- Priority support for production deployments + +**Enterprise users:** +- Dedicated support channels +- SLA-backed response times +- Custom deployment assistance + +### What should I do if I suspect a security issue? + +**For security vulnerabilities:** +1. **Do not post publicly** - security issues should be reported privately +2. **Email security team:** security@phala.network +3. **Include:** Detailed description, reproduction steps, potential impact +4. **Response:** Expect acknowledgment within 24-48 hours + +**For attestation failures:** +```bash +# Verify your measurements +dstack-util show + +# Check blockchain records +# Verify KMS connectivity +# Ensure no unauthorized changes to your application +``` + +**For suspicious activity:** +```bash +# Check certificate transparency logs +# Monitor for unauthorized certificate issuance +# Verify all deployments are authorized +# Review access logs and metrics +``` + +**Best practices:** +- Monitor attestation status regularly +- Set up alerts for deployment changes +- Keep dstack components updated +- Follow security advisories + diff --git a/docs/overview/glossary.mdx b/docs/overview/glossary.mdx new file mode 100644 index 00000000..67b67b18 --- /dev/null +++ b/docs/overview/glossary.mdx @@ -0,0 +1,297 @@ +--- +title: "Terms / Glossary" +description: "An authoritative reference for every core concept, component, and cryptographic primitive that powers the dstack confidential-computing platform." +--- + +> This glossary defines key dstack terms—what they mean, why they matter, and how they're used—organised A-Z with **bold terms**, *italic highlights*, and helpful links. + +--- + +## A – C + +### **ACME (Automatic Certificate Management Environment)** +Open IETF protocol ([RFC 8555](https://www.rfc-editor.org/rfc/rfc8555)) that lets software request, renew, and revoke TLS certificates without human intervention. +*In dstack*: **dstack-gateway** calls *Certbot* in the DNS-01 flow so you can obtain a valid certificate even when ports 80/443 are fire-walled, guaranteeing "zero-touch" HTTPS for every app. + +### **ACME DNS-01 Challenge** +Flow in which domain control is proven by publishing a TXT record under `_acme-challenge.`. +*In dstack*: used at first boot; the gateway automation injects the TXT record via your DNS provider's API, then cleans it up after issuance. + +### **App-id** +Unique identifier for deployed applications in dstack, typically derived from the application's cryptographic hash. +*In dstack*: used for routing (`.domain.com`), key derivation, and authorization checks with smart contracts. + +### **AppAuth** +Ethereum smart-contract that stores the *allowed container-image hash* for a given application and signals the gateway that a CVM may expose traffic once its **Attestation Quote** matches that hash. +*In dstack*: every new deployment registers its image digest with AppAuth; the gateway consults this contract before adding a route. +Further reading: [Smart-contract basics](https://ethereum.org/en/developers/docs/smart-contracts/) • [dstack component map (GitHub)](https://github.com/Dstack-TEE/dstack#architecture). + +### **Attestation Quote** +Signed report produced by a TEE (e.g. Intel TDX) that hashes each boot component (`RTMR0-3`) and binds them to a verifier-supplied nonce. +*In dstack*: **dstack-guest-agent** forwards the quote to **dstack-kms**; keys flow only when the measurements match the on-chain allow-list. + +### **Blockchain & Smart Contracts** +Deterministic programs (e.g. **KmsAuth**, **AppAuth**) stored on a public chain. They record trusted hashes and decide whether a node, image, or user may receive keys. +*In dstack*: provide decentralised governance and an immutable audit trail—removing single points of failure typical in classical PKI. + +### **CAA Records (Certification Authority Authorization)** +DNS records that specify which certificate authorities are allowed to issue certificates for a domain. +*In dstack*: automatically managed by the gateway to restrict certificate issuance and prevent unauthorized certificates. + +### **Certificate Transparency (CT)** +Public log system ([RFC 6962](https://www.rfc-editor.org/rfc/rfc6962)) for every certificate issued by participating CAs. +*In dstack*: the gateway subscribes to CT feeds and automatically revokes or alerts on rogue certs for your domains. + +### **Certbot** +EFF-maintained ACME client that automates Let's Encrypt operations. +*In dstack*: shipped inside the gateway image; runs on a timer to renew certs ~30 days before expiry without downtime. + +### **CID (Container ID)** +Unique identifier for QEMU virtual machines in dstack, managed by the VMM's allocation pool. +*In dstack*: prevents conflicts between VMs; configured via `cid_start` and `cid_pool_size` in VMM settings. + +### **Compose-hash** +Cryptographic hash of the `docker-compose.yml` file content used for application verification. +*In dstack*: measured into RTMR registers and validated against blockchain records for secure deployments. + +### **Confidential Virtual Machine (CVM)** +VM backed by a hardware TEE (Intel TDX today) providing automatic memory encryption and verifiable launch measurements. +*In dstack*: every user workload lives in a CVM so that the cloud operator, host OS, and hypervisor cannot read or tamper with data in use. + +### **Container Runtime** +Minimal OCI runtime (*runc* / *crun*) inside the CVM image. +*In dstack*: obtains secrets through the guest-agent's Unix socket rather than env-vars, reducing the attack surface for in-container code. + +--- + +## D – F + +### **DCAP (Data-Center Attestation Primitives)** +Intel open-source libraries for local verification of SGX / TDX quotes. +*In dstack*: bundled with KMS to avoid external Intel Attestation Service dependencies. +[GitHub](https://github.com/intel/SGXDataCenterAttestationPrimitives) + +### **Device-id** +Hardware-specific identifier used in attestation and authorization processes. +*In dstack*: helps ensure deployments run only on authorized hardware and prevents unauthorized migration. + +### **DNS TXT Record Lookup** +Method for service discovery using DNS text records with the `_dstack-app-address` prefix. +*In dstack*: enables custom domain routing by publishing application endpoints in DNS records. + +### **Docker Compose** +YAML file describing a multi-container app. +*In dstack*: your unchanged Compose file is parsed by the VMM; each service is mapped to a secure network endpoint. + +### **dstack CLI** +Command-line interface for deploying and managing applications in dstack. +*In dstack*: primary user interface for `deploy`, `list`, `stop` operations and application lifecycle management. + +### **dstack-gateway** +Security-aware reverse proxy: performs WireGuard ingress, RA-TLS validation, automatic certificate management, and CT monitoring. +*Role*: single public entry-point for all CVMs. + +### **dstack-guest-agent** +Small Rust daemon inside every CVM. Exposes RPC for `get_quote`, `get_key`, and `start_container`. +*Role*: sole entity allowed to unseal keys, ensuring secrets never leave the encrypted memory domain. + +### **dstack-kms (Key Management Service)** +CVM-resident service that uses **DCAP** to verify quotes, then deterministically derives per-app keys (disk, TLS, JWT) from a master seed. +*Role*: dstack's root of cryptographic trust. + +### **dstack-os** +Minimal, security-hardened Linux image (~40 MiB) built by **meta-dstack**, stripping out shells, compilers, and package managers to shrink the attack surface. +*Benefit*: identical runtime across TEE hardware and faster boot times. +Further reading: [Phala blog](https://phala.network/posts/Dstack-A-Zero-Trust-Framework-for-Confidential-Containers) • [meta-dstack layer](https://github.com/Dstack-TEE/dstack/tree/main/meta-dstack). + +### **dstack-util** +Comprehensive command-line utility providing TDX attestation, system initialization, cryptographic services, and container management. +*In dstack*: handles full disk encryption setup, RTMR extensions, certificate generation, and system bootstrapping within CVMs. + +### **dstack-vmm (Virtual Machine Manager)** +Rust supervisor on the host that spawns, monitors, and tears down CVMs via QEMU + TDX, and presents a REST/GUI that accepts your `docker-compose.yaml`. +*Role*: bridges DevOps tooling to hardware TEE features. + +### **FDE (Full-Disk Encryption)** +Block-level encryption via Linux *dm-crypt/LUKS*. +*In dstack*: `dstack-util setup` seals the volume key so disks remain unreadable until the CVM passes attestation. + +--- + +## G – M + +### **Gateway Agent** +Service component within the gateway that handles communication with CVMs and manages WireGuard connections. +*In dstack*: configured on port 8090 by default and manages the VPN tunnel establishment. + +### **Guest Agent Socket (`/var/run/dstack.sock`)** +Unix socket through which containers request keys or quotes. +*Guarantee*: secrets bypass the filesystem and environment variables, minimising leakage. + +### **Guest API** +VMM endpoint (`/guest`) that provides proxied access to CVM guest agents. +*In dstack*: enables secure communication between host components and applications running inside CVMs. + +### **Hardware Random Number Generator (RNG)** +On-die entropy source conforming to NIST SP 800-90. +*In dstack*: feeds all cryptographic operations inside the TEE; host RNGs are used only as a secondary pool. + +### **Host API** +VMM endpoint (`/api`) for CVM notifications and host information exchange. +*In dstack*: handles communication between the host system and running CVMs for management operations. + +### **Instance-id** +Unique identifier for specific CVM instances within an application deployment. +*In dstack*: used for tracking individual VM instances and managing their lifecycle and resources. + +### **Intel Trust Domain Extensions (TDX)** +CPU feature set providing encrypted VM memory, DMA isolation, and a new attestation leaf. +*In dstack*: exclusive hardware backend for CVMs (AMD SEV-SNP & ARM CCA on the roadmap). See [Intel TDX specification](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html). + +### **iohash / RTMR Measurement** +SHA-384 hash stored in TDX Runtime Measurement Registers. +*In dstack*: compared against the allow-list in **KmsAuth** before keys are released. + +### **KmsAuth** +Smart-contract that keeps an *allow-list of trusted RTMR hashes* and authorises **dstack-kms** to release keys only when a presented quote matches one of those hashes. +*In dstack*: policy gate for every key-release request. +Further reading: [Ethereum smart-contract docs](https://ethereum.org/en/developers/docs/smart-contracts/) • [dstack README](https://github.com/Dstack-TEE/dstack#readme). + +### **LUKS (Linux Unified Key Setup)** +Standard on-disk format for FDE keys; supports multiple keyslots and PBKDF2/Argon2 hardening. +*In dstack*: initialises NVMe drives attached to CVMs using AES-XTS-Plain64 cipher. + +### **meta-dstack** +Yocto meta-layer that builds the dstack-os image with only the guest-agent, container runtime, and attestation libs. +*Benefit*: smaller footprint and reproducible builds. + +### **MRTD (Measurement of Runtime TDX Data)** +CPU register that records a SHA-384 hash of the *static* TD state (e.g. firmware) at build time—complements dynamic `RTMR0-3`. +*In dstack*: **dstack-kms** and **KmsAuth** validate MRTD inside each quote. +See [kernel.org TDX docs](https://www.kernel.org/doc/html/next/x86/tdx.html). + +--- + +## N – R + +### **Nonce (Attestation)** +Verifier-supplied random value inside the quote to guarantee freshness and stop replay attacks. +*In dstack*: the VMM generates a 256-bit nonce for every attestation request. + +### **OCI (Open Container Initiative)** +Industry standard for container formats and runtimes. +*In dstack*: ensures compatibility with standard Docker containers while adding TEE security layers. + +### **Phala Cloud** +Managed service that runs dstack on bare-metal TDX clusters, providing click-to-deploy CVMs, automatic upgrades, and usage-based billing—ideal for teams that want confidential computing without operating hardware. +Further reading: [Phala docs](https://docs.phala.network/overview/phala-network/dstack) • [dstack architecture blog](https://phala.network/posts/Dstack-A-Zero-Trust-Framework-for-Confidential-Containers) + +### **QEMU** +Open-source machine emulator and virtualizer used by dstack-vmm to create and manage CVMs. +*In dstack*: provides the foundation for running CVMs with TDX support and hardware isolation. + +### **RA-TLS (Remote-Attestation TLS)** +Technique ([arXiv 1801.05863](https://arxiv.org/pdf/1801.05863.pdf)) of embedding a quote in an X.509 extension so the TLS handshake authenticates enclave state. +*In dstack*: the gateway proxies traffic only after validating this extension. + +### **ra-rpc** +Wrapper around pRPC that tunnels every request through RA-TLS, giving internal API calls the same attestation guarantees as HTTPS. +*In dstack*: used by control-plane traffic (VMM ↔ KMS ↔ Guest Agent). + +### **Remote Attestation** +Two-party protocol where a quote is generated and verified (using DCAP certs & CRLs). +*In dstack*: prerequisite for key release, network exposure, and service registration. + +### **Resource Allocation** +Policy-driven distribution of CPU, RAM, and network to CVMs—enforced by cgroups and tc filters. +*Goal*: prevent noisy-neighbour issues while upholding TEE guarantees. + +### **RPC API** +VMM endpoint (`/prpc`) for VM lifecycle management and operations using Protocol Buffers. +*In dstack*: primary interface for programmatic control of CVM deployment and management. + +### **RTMR (Runtime Measurement Registers)** +TDX hardware registers (RTMR0-3) that store cryptographic measurements of system state and boot process. +*In dstack*: extended with application events and verified against blockchain allow-lists for security. + +--- + +## S – Z + +### **Secure Ingress** +Layered design: WireGuard tunnel → RA-TLS termination → service routing. +*Outcome*: traffic is encrypted on the WAN and remains cryptographically bound to the attested CVM on the LAN. + +### **SGX Sealing** +Intel SGX feature for encrypting data with hardware-derived keys that persist across reboots. +*In dstack*: used in Local-Key-Provider mode for persistent key storage without external KMS dependency. + +### **Supervisor** +Process management component that handles CVM lifecycle operations and resource monitoring. +*In dstack*: integrates with VMM to ensure reliable CVM startup, monitoring, and cleanup operations. + +### **TDX Module Specification** +Official Intel document detailing TDX semantics—recommended starting point for low-level implementers. + +### **tdx-attest** +Rust crate that talks to the TDX module to fetch quotes, extend RTMRs, and bundle them into RA-TLS certificates. +*In dstack*: compiled into the guest-agent so every CVM can self-serve attestation material. +GitHub: [tdx-attestation-sdk](https://github.com/automata-network/tdx-attestation-sdk) + +### **TLS Passthrough** +Gateway routing mode where TLS termination is handled by the application rather than the gateway. +*In dstack*: enabled by appending 's' to domain names (`s.domain.com`) for end-to-end encryption. + +### **TLS Termination** +Gateway mode where HTTPS connections are decrypted at the gateway and forwarded as HTTP to applications. +*In dstack*: default mode for `.domain.com` routing with automatic certificate management. + +### **Trusted Execution Environment (TEE)** +Hardware-enforced enclave yielding confidentiality and integrity even against a malicious OS. +*In dstack*: foundational primitive—everything else is orchestration. +See [GlobalPlatform TEE architecture](https://globalplatform.org/specs-library/tee-systems-architecture/). + +### **Web UI** +VMM endpoint (`/`) providing HTML console for browser-based management of CVMs and applications. +*In dstack*: accessible at `http://localhost:9080` for deployment monitoring and log viewing. + +### **WireGuard** +Modern VPN protocol using Curve25519 + ChaCha20-Poly1305. +*In dstack*: links gateway replicas into an authenticated mesh and protects east-west traffic. +Whitepaper: [WireGuard paper](https://www.wireguard.com/papers/wireguard.pdf) + +### **X25519** +Elliptic curve Diffie-Hellman key agreement protocol using Curve25519. +*In dstack*: used for cryptographic key derivation and secure communication establishment. + +### **Zero Trust TLS** +Security model where every connection is authenticated and encrypted regardless of network location. +*In dstack*: implemented through RA-TLS to ensure all communications are cryptographically bound to attested CVM state. + +### **Zero-Knowledge Proof (ZKP)** +Cryptographic proof that reveals nothing except validity—enabling privacy-preserving audits. +*Future use*: optional layer for apps that must prove correct execution off-chain. + +### **ZFS** +Advanced file system providing data integrity, snapshots, and encryption features. +*In dstack*: used with Blake3 checksums and encryption for secure data storage within CVMs. + +--- + +## 📑 Reference Index + +| Spec / Paper / Repo | Description | +|---------------------|-------------| +| RFC 8555 | Automatic Certificate Management Environment | +| RFC 6962 | Certificate Transparency | +| Intel DCAP repo | github.com/intel/SGXDataCenterAttestationPrimitives | +| WireGuard Whitepaper | wireguard.com/papers/wireguard.pdf | +| Intel TDX Spec | intel.com → Trust Domain Extensions | +| arXiv 1801.05863 | Integrating SGX Remote Attestation with TLS | +| LUKS FAQ | cryptsetup wiki | +| GlobalPlatform TEE SysArch | globalplatform.org specs | +| OCI Runtime Spec | opencontainers.org/about/overview/ | +| dstack GitHub | github.com/Dstack-TEE/dstack | +| Phala Network | phala.network | + + diff --git a/docs/overview/introduction.mdx b/docs/overview/introduction.mdx new file mode 100644 index 00000000..9a2bc47d --- /dev/null +++ b/docs/overview/introduction.mdx @@ -0,0 +1,55 @@ +--- +title: "What is DStack?" +description: "DStack lets you run your apps in a secure, private environment that no one else can access or tamper with - not even cloud providers or system administrators. Think of it as a protective bubble for your applications. +" +--- + +## What is Solves for + +When you run apps on regular cloud servers, you have to trust the cloud provider won't peek at your data, system administrators won't modify your app, and hackers won't break into the server. + +**With DStack, you don't have to trust anyone.** Your app runs in special secure hardware that keeps everything private and proves it's running exactly as intended. + +Before and After dstack comparison + +## How does it work? + +DStack uses **Trusted Execution Environments (TEEs)**—special security built into modern chips. This creates a private, encrypted space for your app. + +**What happens:** +Your app runs in a secure "bubble"—everything is encrypted. +No one can see inside—not the cloud, not hackers, not anyone. +You can prove it's secure—anyone can check your app is running in real secure hardware. +Your app works as usual—no code changes needed. + +--- + +## Why does this matter? + +**Privacy:** Your data stays private, even on someone else's server. +**Trust:** Anyone can verify your app is running the code you claim. +**Security:** Even if the server is hacked, your app and data are safe. +**Compliance:** Great for sensitive data that needs strict privacy. + +--- + +## What makes DStack special? + +**Easy deployment:** Upload your Docker containers—no code changes. +**Portable security:** Move your secure app between clouds. +**Verifiable trust:** Anyone can check your app is running in real secure hardware. +**Web access:** Users connect securely over HTTPS. + +--- + +## Common use cases + +**Private AI models:** Run AI without exposing data or model weights. +**Sensitive data processing:** Analyze confidential info safely. +**Financial apps:** Handle transactions and sensitive data. +**Healthcare systems:** Process medical records with privacy. +**Multi-party computation:** Compute together without sharing raw data. diff --git a/docs/overview/key-features.mdx b/docs/overview/key-features.mdx new file mode 100644 index 00000000..425ddbe9 --- /dev/null +++ b/docs/overview/key-features.mdx @@ -0,0 +1,102 @@ +--- +title: "TDX Technology" +description: "DStack brings confidential computing to everyday development workflows without forcing teams to rewrite code or rethink their toolchains. Here are the features that make secure deployment simple and powerful. +" +--- +# Out-of-the-box benefits of using and deploying with dstack + +
+ {/* Hardware-Enforced Isolation */} +
+ + + + + +

Hardware-Enforced Isolation

+

+ Every workload runs inside a processor-level Trusted Execution Environment (TEE). The CPU encrypts memory on the fly, sealing it off from the operating system, hypervisor, and anyone with physical access. +

+
+ + {/* Remote Attestation */} +
+ + + + + +

Remote Attestation

+

+ DStack exposes a built-in attestation API that packages cryptographic evidence of the exact code, configuration, and TEE firmware your service is running on. Third parties can verify this proof before exchanging secrets or traffic. +

+
+ + {/* Zero-Code-Modification Deployment */} +
+ + + + + + +

Zero-Code-Modification Deployment

+

+ Container images that work in staging can be deployed directly to DStack with no SDK, no recompilation, no enclave-specific branches. The platform transparently adds the security layer at runtime. +

+
+ + {/* Decentralized Key Management */} +
+ + + + + + +

Decentralized Key Management

+

+ Encryption keys are issued, rotated, and retired through a blockchain-backed coordination service. Key custodianship is distributed with no single vault to breach or subpoena. +

+
+ + {/* Automated Certificate Lifecycle */} +
+ + + + + + +

Automated Certificate Lifecycle

+

+ TLS certificates are automatically generated, bound to specific enclaves, and renewed just-in-time before expiry. End-to-end encrypted channels with zero downtime and no surprise certificate failures. +

+
+ + {/* Intuitive Web Dashboard */} +
+ + + + + + + + +

Intuitive Web Dashboard

+

+ Replace command-line complexity with a real-time dashboard that shows enclave health, performance counters, and audit trails. Scale, pause, or revoke workloads with a click using role-based access control. +

+
+
+ +dstack lets you push the same containers you run today into CPU-encrypted enclaves, so code and data stay private while hardware-level crypto keeps performance high. +Every deployment is attested for integrity, keys live in a shared on-chain vault, TLS certs renew themselves, and all traffic stays encrypted end to end. + +A point-and-click dashboard replaces CLI wrangling, language-agnostic SDKs plug into any stack, and the platform auto-scales, heals, and logs without leaking sensitive info. +You get an immutable audit trail, one-click compliance reports, + +and a supply-chain filter that blocks unverified images—secure infrastructure without the rewrite. + +dstack is built to be developer-friendly: it takes care of most security challenges and infrastructure dependencies for you. This means you can build scalable, compliant cloud platforms using simple tools and strong security guarantees—without extra hassle. Move fast, stay safe, and keep your existing workflows. diff --git a/docs/overview/what-is-dstack.mdx b/docs/overview/what-is-dstack.mdx new file mode 100644 index 00000000..a0879eeb --- /dev/null +++ b/docs/overview/what-is-dstack.mdx @@ -0,0 +1,79 @@ +--- +title: "DStack Architecture" +description: "How DStack's components work together to create secure, verifiable applications using Intel TDX technology" +--- + +# DStack Architecture + +DStack is an open framework that makes it easy for developers to build confidential computing platforms. It provides SDKs that help you deploy your containerized applications into Intel TDX Trusted Execution Environments (TEEs) without needing to change your existing workflow. DStack was created by Kevin Wang and contributors from Phala Network, inspired by Andrew Miller from Flashbots, with additional contributions from Nethermind and the wider community. + +--- +## Core Design Principles + +
+
+

1. Use your existing tools

+

+ You work with dstack just like you do with Docker, REST APIs, and web dashboards. No need to learn new tools or change how you build and run your apps. +

+
+
+

2. Hardware Abstraction

+

+ The platform provides a consistent interface across different TEE implementations, preventing vendor lock-in and enabling workload portability between Intel TDX, AMD SEV, and future hardware platforms. +

+
+
+

3. Verifiable Security

+

+ Every component in the dstack ecosystem produces cryptographic attestations, creating an auditable chain of trust from hardware to application that can be independently verified. +

+
+
+

4. Decentralized Code Governance

+

+ Critical security decisions—key management, code authorization, update policies—are governed by blockchain smart contracts, eliminating single points of control. +

+
+
+ +--- +## How the Magic Happens + +DStack transforms your regular Docker containers into secure, verifiable applications through a sophisticated architecture built on Intel TDX technology. When you deploy an application, five core components work seamlessly together: + +**The Virtual Machine Manager (dstack-vmm)** runs on bare TDX host hardware and manages the complete lifecycle of your Confidential Virtual Machines. It handles VM creation, configuration, and deployment orchestration while ensuring each CVM is properly isolated and measured during boot. You interact with it through a web interface at port 9080, where you can deploy docker-compose.yaml files, monitor VM status, and access logs. + +**The Gateway (dstack-gateway)** acts as your secure front door, operating as a reverse proxy that forwards TLS connections to your CVMs. It provides multiple access patterns: standard routing where `.` maps to port 80 in your CVM, port-specific routing with `-.`, and TLS passthrough using the 's' suffix for applications managing their own certificates. Under the hood, it uses WireGuard VPN to create encrypted tunnels between the gateway and CVMs. + +**The Guest Agent (dstack-guest-agent)** lives inside your CVMs, serving as the bridge between your containerized applications and the secure environment. Your applications interact with it through a Unix socket mounted at `/var/run/dstack.sock` to obtain TDX quotes for remote attestation, maintaining security boundaries while enabling necessary communication. + +--- +## The Security Infrastructure + + +DStack's security model centers on Intel TDX technology, which provides hardware-based isolation for confidential workloads. The system uses remote attestation to verify application integrity and relies on cryptographic measurements stored in hardware registers. + +**Key Management Service (dstack-kms)** generates and manages cryptographic keys for CVMs, integrating with blockchain-based authorization through smart contracts. It validates TEE attestation reports before releasing keys, ensuring only trusted environments running verified code can access sensitive cryptographic material. The KMS supports key derivation for disk encryption, environment variable encryption, and certificate generation. + +**Secret Management** happens through Encrypted Environment Variables. When you deploy applications, secrets are encrypted client-side using public keys provided by the KMS, transmitted securely to the VMM, and only decrypted within the Confidential VM using keys derived from TDX attestation. This ensures sensitive data remains protected throughout the entire deployment process. + +**Certificate Management** includes automated TLS certificate management through Let's Encrypt and Cloudflare DNS integration. The system implements Certificate Authority Authorization (CAA) records to restrict certificate issuance and monitors Certificate Transparency logs to detect unauthorized certificates, preventing man-in-the-middle attacks. + +The security architecture includes TDX quotes for attestation, measurement registers (MRTD, RTMR0-3) for tracking system state, and blockchain-based smart contracts for authorization. This multi-layered approach ensures only authorized code runs in the trusted environment with all interactions secured and auditable. + +--- + +## From Development to Production + +DStack bridges the gap between familiar development tools and advanced confidential computing. You deploy applications using standard docker-compose.yaml files through the web interface, while DStack automatically manages the complexities of TEE deployment, key management, and secure networking. + +**Hardware Requirements:** You need a TDX-compatible server with a public IPv4 address, at least 16GB RAM, and 100GB free disk space. The deployment process involves setting up the TDX host with necessary dependencies, building or downloading DStack components, configuring and running the core services, then deploying applications through the familiar Docker interface. + +**Real-World Benefits:** The platform provides a developer-friendly experience with familiar Docker tools, hardware-based security through Intel TDX, automated key management and certificate handling, secure networking with built-in VPN and TLS termination, and remote attestation capabilities for trust verification. + +**Process Management** is handled by the supervisor component, which manages and monitors running processes across the DStack system, ensuring reliable operation of all services and handling process lifecycle management with comprehensive logging and debugging capabilities for troubleshooting deployments. + +--- + +**The Bottom Line:** DStack makes confidential computing accessible by providing hardware-based security with familiar Docker tooling, enabling secure deployment of containerized workloads in environments requiring data privacy, code protection, and verifiable execution. diff --git a/docs/public/background.png b/docs/public/background.png new file mode 100644 index 00000000..e69de29b diff --git a/docs/public/favicon.png b/docs/public/favicon.png new file mode 100644 index 00000000..f6b3eef6 Binary files /dev/null and b/docs/public/favicon.png differ diff --git a/docs/public/logo/dark.png b/docs/public/logo/dark.png new file mode 100644 index 00000000..961ae900 Binary files /dev/null and b/docs/public/logo/dark.png differ diff --git a/docs/public/logo/light.png b/docs/public/logo/light.png new file mode 100644 index 00000000..35e0cd30 Binary files /dev/null and b/docs/public/logo/light.png differ diff --git a/docs/security-research/extra-sec-ops/before-reading.mdx b/docs/security-research/extra-sec-ops/before-reading.mdx new file mode 100644 index 00000000..8f554404 --- /dev/null +++ b/docs/security-research/extra-sec-ops/before-reading.mdx @@ -0,0 +1,80 @@ +--- +title: "Security Modules" +description: "Summary and navigation for supplementary security modules in dstack" +--- + +# Before You Continue: Prerequisite Reading & Navigation Guide + +
+
+ ⚠️ before reading this section, make sure you have covered the following foundational topics: +
+ +
+ note: the sections below focus on supplementary and utility modules (such as certbot, ct monitor, iohash, and host api security). these are not required reading for understanding the core dstack platform, but are valuable for deep research or if you need to understand the full security landscape. if you are new to dstack or have not yet reviewed the main systems, we recommend starting with the links above. +
+
+ +# Overview: Supplementary Security Modules in dstack + +This section provides analysis of the supplementary security modules that enhance dstack's TEE (Trusted Execution Environment) infrastructure. These modules—**Certbot TEE Security**, **Certificate Transparency Monitor**, **Host API Security**, and **IOHash Security**—work together to provide comprehensive security coverage across certificate management, monitoring, host operations, and cryptographic verification. + +Each module addresses a specific security domain while integrating with dstack's core TEE architecture to provide layered protection and verification capabilities throughout the platform. + + diff --git a/docs/security-research/extra-sec-ops/cert-client-security.mdx b/docs/security-research/extra-sec-ops/cert-client-security.mdx new file mode 100644 index 00000000..703e712a --- /dev/null +++ b/docs/security-research/extra-sec-ops/cert-client-security.mdx @@ -0,0 +1,52 @@ +--- +title: "Cert Client Security" +description: "Certificate verification and client-side attestation integration in dstack" +--- + +# Certificate Client Security + +The certificate client component serves as the critical interface between applications and dstack's hardware-backed certificate authority system. This component handles client-side certificate requests and signing operations while integrating comprehensive hardware attestation verification, ensuring that every certificate issued is cryptographically bound to verified trusted execution environments. + +## Security Architecture and Trust Model + +The cert-client implements a dual-mode certificate authority system that supports both local CA operations and remote KMS-based signing with full attestation verification. In local mode, the system performs direct CA certificate signing, while KMS mode establishes remote attestation through RA-RPC clients with mutual TLS authentication. This flexibility allows the system to operate in various deployment scenarios while maintaining consistent security guarantees. + +The cryptographic foundation relies entirely on ECDSA P-256 SHA-256 for all certificate signing operations, ensuring industry-standard elliptic curve cryptography throughout the system. Certificate signing requests incorporate PKCS#8 DER encoding and ASN.1 signature verification, with all signatures validated against embedded public keys using the ring cryptography library's ECDSA implementation. + +## Hardware Attestation Integration + +The core security mechanism integrates Intel TDX (Trust Domain Extensions) attestation directly into X.509 certificates through a sophisticated quote generation and embedding process. The system generates TDX quotes containing hardware measurements and embeds them as custom certificate extensions using enterprise-registered OIDs. This attestation process creates an unbreakable cryptographic binding between certificate public keys and hardware report data through SHA-512 hashing. + +The attestation system defines specific content types for quote generation, covering KMS root CA verification, RA-TLS certificates, and application-specific data. Report data generation supports configurable hash algorithms including SHA-256, SHA-384, SHA-512, and SHA-3 variants, with SHA-512 serving as the default for maximum security. + +## Trusted Computing Base Validation + +Comprehensive TCB validation prevents execution in insecure environments by implementing strict security policies. For TDX environments, debug mode execution is explicitly prohibited, ensuring that certificates can only be generated in production-ready hardware. This validation extends to SGX enclaves, enforcing production-only execution by checking debug attributes and preventing any certificate generation in development or debugging scenarios. + +The system implements cryptographic event log replay functionality to ensure runtime integrity through RTMR (Runtime Measurement Register) verification. Event log chains are validated using SHA-384 hashing, with measurements verified against hardware-reported values to prevent runtime tampering and ensure execution environment integrity. + +## Certificate Extension Security and Verification + +Custom X.509 extensions embed attestation data using carefully structured DER encoding. Quote extensions store raw TDX quotes, while event logs are JSON-serialized and embedded for comprehensive measurement verification. Application identity becomes cryptographically bound through specialized app-id extensions, enabling fine-grained policy enforcement based on application identity and deployment configuration. + +The RA-RPC client implements comprehensive TLS security with integrated attestation verification. Client certificates undergo validation through hardware quote verification, ensuring that remote endpoints execute within trusted environments. The system extracts attestation data from peer certificates and validates against Intel's Provisioning Certificate Caching Service (PCCS) infrastructure for complete trust chain verification. + +## Key Provider Integration and Certificate Signing + +The certificate request process supports multiple key provider modes with distinct security models designed for different operational requirements. Local key providers utilize direct CA operations for simplified deployments, while KMS providers establish temporary certificate authority relationships through RA-TLS certificate generation. This approach enables secure key escrow while maintaining strict hardware attestation requirements. + +Certificate signing requests implement mandatory confirmation strings to prevent unauthorized signing operations, with all requests including hardware quotes and event logs when attestation is enabled. This ensures that every certificate issued is cryptographically bound to execution environment measurements, creating an audit trail that can be independently verified. + +## Verification Pipeline and Application Identity + +The attestation verification pipeline implements multi-stage validation including quote parsing, collateral verification through PCCS, and RTMR consistency checking. Report data validation ensures that certificate public keys match attested measurements, effectively preventing key substitution attacks and maintaining the integrity of the entire certificate issuance process. + +The system extracts comprehensive application metadata from event logs, including application identifiers, compose file hashes, and instance identifiers. This capability enables sophisticated policy enforcement based on application identity and deployment configuration, allowing organizations to implement fine-grained access controls and compliance requirements. + +## Security Properties and Compliance + +The implementation adheres to X.509 certificate standards while extending functionality through custom OIDs registered under the enterprise namespace. The system maintains backward compatibility through conditional feature inclusion and graceful degradation for non-TEE environments, ensuring broad applicability while preserving security benefits where hardware support is available. + +Certificate configuration supports comprehensive usage restrictions including server authentication, client authentication, and extended key usage purposes. Subject alternative names and organizational constraints provide additional policy enforcement mechanisms, while flexible trust store configuration supports both built-in root certificate support and custom CA certificate injection for air-gapped deployments. + +The cert-client security model fundamentally depends on underlying TDX hardware security guarantees and PCCS infrastructure reliability. All cryptographic operations rely on hardware random number generation and secure key storage within the TEE environment, with the attestation verification pipeline requiring network connectivity for quote validation, which may impact certain deployment scenarios but ensures comprehensive security validation. diff --git a/docs/security-research/extra-sec-ops/certbot-security.mdx b/docs/security-research/extra-sec-ops/certbot-security.mdx new file mode 100644 index 00000000..593ff258 --- /dev/null +++ b/docs/security-research/extra-sec-ops/certbot-security.mdx @@ -0,0 +1,44 @@ +--- +title: "Certbot TEE Security" +description: "Analysis of automated certificate management and ACME protocol implementation in dstack TEE" +--- + +# Certbot TEE Security + +The Certbot integration within dstack represents a fundamental shift from traditional certificate management to hardware-backed, attestation-bound certificate generation. This system replaces standard cryptographic operations with TEE-derived security mechanisms, creating certificates that provide cryptographic proof of their generation within trusted execution environments. + +## Hardware-Sealed Certificate Management + +Rather than using conventional key generation methods, the TEE-integrated Certbot leverages dstack's key derivation framework to create ECDSA key pairs from TEE-sealed master keys. This approach ensures that private keys are intrinsically bound to the specific TEE environment and application state through measurement-based context data that incorporates TDX Runtime Measurement Register (RTMR) values and application-specific identifiers. + +The security model fundamentally changes how we think about certificate trust. Instead of relying solely on certificate authority validation, these certificates carry embedded proof of their creation within verified hardware environments, enabling new levels of assurance for SSL/TLS communications. + +## Attestation-Bound Certificate Generation + +Each certificate generated through this system embeds TDX attestation quotes as custom X.509 extensions, following established attestation patterns within dstack's security architecture. The quote generation process creates attestation data containing the certificate's public key hash, establishing a cryptographic binding between the certificate and the current TEE state. + +This integration utilizes the guest agent's RPC interface to generate attestation quotes with certificate public keys as report data. The resulting certificates don't just authenticate identity—they prove the integrity and trustworthiness of the environment that created them. + +## Enclave-Resident Operations + +All certificate operations occur entirely within the TEE boundary using the guest agent's key derivation services. Private keys never exist in plaintext outside the secure enclave, with all signing operations happening within the protected environment. This architectural decision ensures that even if the host system is compromised, the certificate private keys remain protected by hardware security guarantees. + +The system builds upon existing TLS key generation services to create attestation-enabled certificates directly within the TEE environment, maintaining the security properties that make confidential computing valuable. + +## Enhanced ACME Protocol Integration + +The ACME client implementation includes attestation proofs in certificate requests, potentially through new challenge types or additional metadata embedded in the standard ACME flow. The existing DNS-01 challenge process can be enhanced to include TEE attestation validation by certificate authorities that support this verification model. + +Key renewal operations maintain TEE binding by deriving new keys from the same master key material while updating embedded attestation quotes to reflect current TEE state. This ensures that certificate lifecycle management preserves the security properties established during initial generation. + +## Security Guarantees and Trust Model + +This architecture provides several critical security guarantees that extend beyond traditional certificate management. Hardware-backed key security ensures that private keys are derived from and sealed to TEE measurements, making them accessible only within verified environments. Attestation-bound certificates provide cryptographic proof of their origin within verified TEE instances, while measurement-based validation enables end-to-end verification from hardware through application layers. + +The system creates tamper-evident operations through event log records of all certificate lifecycle events, stored in RTMR3 to provide cryptographic proof within the attestation chain. This comprehensive approach enables zero-trust verification where certificates include all necessary attestation data for independent verification by relying parties. + +## Integration with dstack's Security Infrastructure + +The TEE-integrated Certbot leverages dstack's existing security infrastructure, requiring minimal changes to core attestation and key derivation systems. This design maintains compatibility with standard ACME protocols while adding TEE-specific security enhancements, ensuring that certificates issued through this system enable new use cases for high-assurance SSL/TLS certificates in confidential computing environments. + +The integration demonstrates how traditional internet security protocols can be enhanced with hardware-backed security guarantees, creating a new class of certificates that provide both identity authentication and execution environment verification. diff --git a/docs/security-research/extra-sec-ops/ct-monitor-security.mdx b/docs/security-research/extra-sec-ops/ct-monitor-security.mdx new file mode 100644 index 00000000..ceae0f84 --- /dev/null +++ b/docs/security-research/extra-sec-ops/ct-monitor-security.mdx @@ -0,0 +1,54 @@ +--- +title: "CT Monitor Security" +description: "Certificate Transparency monitoring and anomaly detection for dstack TEE infrastructure" +--- + +# Certificate Transparency Monitor Security + +The Certificate Transparency monitor serves as a critical security component that continuously watches for unauthorized certificate issuance across dstack domains. This system queries the crt.sh database to detect newly issued certificates and validates them against expected public keys managed by the dstack gateway, immediately alerting administrators to any suspicious or unauthorized certificate activity. + +## Purpose and Security Model + +The CT monitor implements a defense-in-depth approach to certificate security through continuous monitoring of Certificate Transparency logs combined with validation against TEE-managed public keys from the dstack gateway. This dual-layer protection includes CAA DNS records that restrict certificate issuance to authorized accounts and RA-TLS attestation embedding for certificate authenticity verification. + +The monitoring system operates by establishing a trusted baseline of legitimate certificates and continuously comparing new certificate issuance against this known-good state. When certificates appear in transparency logs that don't match the expected public keys, the system immediately triggers alert mechanisms to notify security teams of potential compromise or unauthorized issuance. + +## Monitoring Architecture and Implementation + +The core monitoring logic queries the crt.sh database at regular intervals and validates each discovered certificate against a trusted set of public keys retrieved from the dstack gateway RPC endpoint. The system maintains this trusted key set by fetching known public keys from the gateway's ACME information endpoint, which exposes historical certificate public keys through the certbot working directory. + +Domain validation ensures that only legitimate domains are monitored through regex pattern matching, while the monitor processes Certificate Transparency log entries sequentially and tracks the last checked entry to avoid reprocessing. The system operates with a 60-second polling interval, fetching up to 10,000 log entries per query to provide reasonable detection latency while avoiding rate limiting from the crt.sh service. + +## Certificate Management Integration + +The system integrates deeply with dstack's certificate management infrastructure through the certbot component, which manages the complete ACME certificate lifecycle within the TEE environment. This integration includes automatic ACME account creation, CAA record configuration, and certificate renewal processes that maintain security boundaries while enabling operational efficiency. + +CAA records provide the first line of defense by automatically restricting certificate issuance to the dstack gateway ACME account. These DNS-based controls prevent unauthorized Certificate Authorities from issuing certificates for monitored domains, though the CT monitor provides essential detection capabilities even if CAA protections are bypassed through DNS manipulation or other attack vectors. + +## TEE Security Integration and Attestation + +Certificates within the dstack ecosystem can embed TEE attestation quotes using custom X.509 extensions, providing cryptographic proof that certificates were generated within verified TEE environments. The system supports embedding quotes, event logs, and application IDs in certificates for enhanced verification, creating a comprehensive trust model that extends beyond traditional certificate authority validation. + +The gateway manages certificate private keys within sealed TEE environments and exposes only public key information for CT monitoring validation. This architecture ensures that even if monitoring systems are compromised, the underlying certificate private keys remain protected by hardware security guarantees. + +## Threat Model and Security Considerations + +The primary threat addressed by the CT monitor is unauthorized certificate issuance for dstack domains, which could enable man-in-the-middle attacks or other security compromises. The system mitigates this through multiple complementary mechanisms including CAA records restricting authorized CAs, continuous CT log monitoring for detection, and public key validation against TEE-managed keys. + +DNS manipulation represents a secondary threat vector where CAA records could be modified if DNS infrastructure is compromised. The CT monitor provides detection capabilities that function even when CAA protections are bypassed, ensuring that unauthorized certificates are detected regardless of the attack method used. + +The system currently relies solely on crt.sh for Certificate Transparency data, creating a potential single point of failure. While this dependency introduces some risk, the robust error handling for network failures, invalid certificates, and missing public keys ensures that critical errors are logged for investigation while maintaining service continuity. + +## Cryptographic Security and Performance + +The monitoring system uses ECDSA P-256 keys for certificate signing operations and validates signatures using the ring cryptography library. Certificate signing requests require proper authentication and verification throughout the process, ensuring that only legitimate certificates can be issued and validated. + +Error handling mechanisms ensure robust operation under various failure conditions including network connectivity issues, invalid certificate formats, and missing public key references. The system implements comprehensive logging for critical errors while maintaining operational continuity and avoiding false positive alerts that could overwhelm security teams. + +## Configuration and Integration Points + +The monitor requires secure communication with the dstack gateway RPC endpoint through configuration that includes gateway URI specifications and domain monitoring patterns. The gateway provides ACME account information and historical public keys through authenticated RPC calls, ensuring that monitoring data remains accurate and up-to-date. + +Integration with Cloudflare enables DNS challenges and CAA management, with configuration parameters including ACME server URLs, Cloudflare credentials, and certificate management settings. This integration ensures that certificate lifecycle management processes remain automated while maintaining security controls. + +The CT monitor represents a critical component of dstack's layered security approach, providing continuous monitoring capabilities that complement hardware-based security guarantees and enable rapid detection of potential security incidents related to certificate management and domain security. diff --git a/docs/security-research/extra-sec-ops/host-api-security.mdx b/docs/security-research/extra-sec-ops/host-api-security.mdx new file mode 100644 index 00000000..a84c9255 --- /dev/null +++ b/docs/security-research/extra-sec-ops/host-api-security.mdx @@ -0,0 +1,68 @@ +--- +title: "Host API Security" +description: "Secure host management and orchestration API for dstack TEE infrastructure" +--- + +# Host API Security Architecture + +The Host API represents the foundational security interface for TEE host management within dstack, implementing a three-endpoint secure interface that provides critical security services including host information retrieval, event notification handling, and sealing key provisioning. This API server operates as an integral component of the VMM using the RA-RPC framework for secure remote procedure calls, establishing the trust foundation for all confidential computing operations. + +## Cryptographic Security Foundation + +The system employs military-grade cryptographic algorithms designed for enterprise-level security requirements. The cryptographic foundation relies on HKDF-SHA256 for secure key derivation using a dedicated "RATLS" salt, ECDSA P-256 for digital signatures with PKCS#8 encoding, and X25519 for Diffie-Hellman key exchange derived from ECDSA keys. This comprehensive cryptographic suite supports multi-algorithm hash operations including SHA-256, SHA-384, SHA-512, SHA-3, and Keccak variants. + +Key derivation functions implement cryptographically secure context-based derivation where derived keys are generated using HKDF with configurable context data and output sizes up to 256 bytes. The system ensures forward secrecy through proper key rotation and derivation chains, preventing compromise of future keys even if current key material is exposed. + +## Authentication and Authorization Framework + +The Host API enforces strict mutual TLS authentication with comprehensive client certificate verification and attestation validation. The authentication system extracts and validates app-specific identifiers from client certificates using custom OID extensions, creating a robust identity verification mechanism that extends beyond traditional certificate validation. + +The system utilizes custom X.509 certificate extensions with enterprise-registered OIDs for embedding attestation data. Quote extensions store SGX and TDX quotes, event log extensions preserve TDX event logs, app ID extensions provide application identification, and certificate usage extensions handle special certificate purposes. This extension system creates a comprehensive identity and attestation framework. + +## Intel TDX Attestation and Hardware Security + +The attestation system implements comprehensive TDX quote verification using Intel's DCAP QVL library for collateral retrieval and verification. The system performs strict Trusted Computing Base validation including debug mode prevention and signer verification, ensuring that only production-ready hardware environments can participate in secure operations. + +Runtime measurement validation utilizes cryptographic event log replay using SHA-384 hashing to validate Runtime Measurement Registers, ensuring boot-time and runtime integrity. Event logs are validated against computed measurements with strict matching requirements, preventing runtime tampering and ensuring execution environment integrity throughout the operational lifecycle. + +The quote content validation framework supports multiple content types for quote data validation including KMS root CA verification, RA-TLS certificates, and application-specific data with configurable hash algorithms. This flexibility enables diverse security policies while maintaining consistent verification standards. + +## Secure Key Management and Provisioning + +The Host API provides hardware-backed sealing key provisioning through integration with dedicated key provider services. The system uses NaCl sealed boxes for secure key transport with public key cryptography, ensuring that sensitive key material remains protected during transmission and storage operations. + +Key provider communication implements secure TCP-based protocols with length-prefixed JSON messaging and payload limits for quote transmission. All key operations require valid TDX quotes and SGX enclave verification before key release, creating a comprehensive verification pipeline that prevents unauthorized key access. + +The KMS system manages multiple key types including TLS CA certificates for trust anchor establishment, disk encryption keys for full disk encryption, environment variable encryption keys using X25519, ECDSA keys for Ethereum-compatible signing operations, and K256 signatures with root key validation. This diverse key management capability supports various cryptographic requirements within the confidential computing environment. + +## Communication Security and Isolation + +The Host API utilizes VSOCK communication channels for secure host-guest isolation with dedicated CID and port assignments. This approach provides hardware-enforced isolation between host and guest environments, preventing unauthorized access and ensuring that sensitive operations remain contained within appropriate security boundaries. + +Request processing security implements comprehensive request validation with configurable size limits, content-type verification, and method-specific payload restrictions. All requests undergo multi-layer security processing including attestation verification and certificate validation, ensuring that only authorized and verified requests can access sensitive API endpoints. + +## Advanced Security Controls and Multi-Tenant Isolation + +The VMM provides secure VM lifecycle management with hardware isolation controls including NUMA node pinning for hardware isolation, hugepage allocation for performance and security, GPU attachment security with PCI device validation, and resource quota enforcement per tenant. These controls ensure that multiple tenants can operate securely within the same hardware environment without compromising isolation guarantees. + +The system enforces strict tenant isolation through hardware resource partitioning via NUMA nodes, memory and CPU quota limits with configurable maximums, network isolation with dedicated address spaces, and encrypted environment variables per application. This comprehensive isolation model prevents cross-tenant information leakage and ensures that confidential workloads remain protected. + +## Certificate Authority and Attestation Operations + +The system implements secure RA-TLS certificate generation with embedded attestation data and configurable validity periods up to 10 years. Certificates include digitally signed attestation quotes and event logs for complete verification, enabling comprehensive trust establishment for secure communications. + +Certificate signing processes implement strict validation requirements including confirmation word verification, ECDSA signature validation using P-256 curves, public key format verification with DER encoding, and algorithm compatibility checks. These requirements ensure that only authorized certificate requests can be processed and that all certificates maintain cryptographic integrity. + +## Production Security Configuration + +The KMS implements enterprise-grade TLS configuration with mutual TLS enforcement and CA certificate validation. The system supports configurable client certificate requirements, dedicated certificate directories for secure storage, and subject name validation with domain verification. This comprehensive TLS configuration ensures that all communications remain secure and properly authenticated. + +Authentication API integration supports multiple authentication backends including webhook-based authentication and development mode overrides with configurable gateway app ID validation. This flexibility enables diverse deployment scenarios while maintaining consistent security standards across different operational environments. + +## Security Monitoring and Compliance + +The Host API implements detailed security event logging with request tracing, method identification, and unique request ID assignment for audit trail maintenance. This comprehensive logging capability enables security teams to track all API interactions and investigate potential security incidents effectively. + +Error handling security utilizes sanitized error messages and structured error encoding that prevents information disclosure while maintaining debugging capability. This approach ensures that security-sensitive information remains protected even when errors occur during normal operations. + +The Host API security implementation aligns with enterprise security standards including NIST guidelines for cryptographic implementations, Intel TDX specifications for attestation protocols, zero-trust architecture principles with continuous verification, and defense-in-depth security strategies with multiple validation layers. This comprehensive approach ensures that the system meets stringent security requirements for confidential computing workloads while maintaining operational efficiency and scalability. diff --git a/docs/security-research/extra-sec-ops/iohash-security.mdx b/docs/security-research/extra-sec-ops/iohash-security.mdx new file mode 100644 index 00000000..985b5420 --- /dev/null +++ b/docs/security-research/extra-sec-ops/iohash-security.mdx @@ -0,0 +1,38 @@ +--- +title: "IOHash Security Architecture" +description: "Content-addressed storage and cryptographic integrity verification for dstack" +--- + +# IOHash Security Architecture + +IOHash is a specialized cryptographic hashing utility that serves as a critical component in dstack's trusted execution environment. This command-line tool operates as a streaming hash computation service, designed to compute cryptographic digests of data streams while preserving the original data flow—reading from stdin, outputting original data to stdout, and writing hash digests to stderr. + +## Core Purpose and Design + +The utility exists to provide consistent cryptographic operations across dstack's TEE infrastructure. IOHash processes data in efficient 32KB chunks, supporting both file-based operations and Unix pipeline integration without disrupting existing data flows. This design enables seamless integration into existing workflows while providing cryptographic verification capabilities. + +The tool supports an extensive range of industry-standard cryptographic algorithms, including the complete SHA-2 family (SHA-224, SHA-256, SHA-384, SHA-512, and their variants), the SHA-3 family, Keccak variants, and Blake2 algorithms. This comprehensive support ensures compatibility with various security requirements throughout the TEE environment. + +## Integration with dstack's Security Architecture + +IOHash functions as more than a standalone utility—it's deeply integrated into dstack's attestation and verification systems. The algorithms supported by IOHash directly correspond to those used in the broader TEE attestation framework, particularly for processing report data in TDX quotes. This alignment ensures that hash computations performed by IOHash can be seamlessly verified and validated within the complete attestation pipeline. + +The utility uses SHA-512 as its default algorithm, maintaining consistency with the rest of dstack's infrastructure. This standardization simplifies verification processes and reduces the complexity of cross-component validation. + +## Security Integration Points + +The tool integrates with several key components of dstack's security model. It works alongside the guest agent RPC protocol for TDX quote generation, enabling applications to specify hash algorithms for attestation processes. The KMS component utilizes similar cryptographic functions, particularly Keccak256, for key derivation and message signing operations. + +IOHash also supports the event log processing system, which implements measurement replay functionality using SHA-384 hashing. This integration ensures that hash computations can be verified against Runtime Measurement Registers (RTMRs) within the TDX environment, maintaining the integrity of the boot process and runtime measurements. + +## Cryptographic Integrity and Validation + +The security architecture includes comprehensive validation mechanisms that ensure debug modes are disabled and measurements match expected values. IOHash supports the creation of unique application fingerprints based on compose files and instance identifiers, enabling fine-grained security policies and verification processes. + +The utility's design emphasizes both performance and security, utilizing Rust's Digest trait for consistent algorithm handling while maintaining the streaming architecture necessary for high-throughput operations. This approach ensures that cryptographic operations remain efficient even when processing large data volumes. + +## Role in TEE Attestation + +Within the broader dstack ecosystem, IOHash demonstrates a cohesive approach to cryptographic operations where the same algorithms and processing methods are used consistently across different components. From command-line utilities to core attestation services, this consistency reduces complexity and improves the overall security posture of the system. + +The utility serves both immediate operational needs and long-term security requirements, providing a foundation for content-addressed storage, data integrity verification, and seamless integration with dstack's comprehensive TEE security architecture. diff --git a/docs/security-research/gate/gate-attestation-verification.mdx b/docs/security-research/gate/gate-attestation-verification.mdx new file mode 100644 index 00000000..8830f981 --- /dev/null +++ b/docs/security-research/gate/gate-attestation-verification.mdx @@ -0,0 +1,48 @@ +--- +title: "Gateway Attestation and Verification Mechanisms" +description: "Technical implementation details of attestation verification, quote validation, and continuous security monitoring in the dstack gateway" +--- + +# Gateway Attestation and Verification Mechanisms + +Attestation verification in the dstack gateway represents the technical implementation of trust establishment protocols that ensure only genuine, uncompromised confidential virtual machines can participate in the cluster. This process goes beyond simple certificate validation to include hardware-backed cryptographic proof of integrity, real-time verification of execution environment state, and ongoing monitoring of security guarantees. + +The gateway's attestation verification system is designed to handle the complex requirements of modern confidential computing environments, where traditional notions of perimeter security are insufficient. Instead of relying on network-based access controls, the system implements a comprehensive verification framework that can detect tampering, unauthorized modifications, and compromise attempts at the hardware, firmware, and software levels. + +What makes dstack's approach particularly robust is its integration of multiple verification mechanisms into a unified security framework. The system combines Intel TDX attestation with custom authorization contracts, certificate transparency monitoring, and real-time health assessment to create a multi-layered verification system that can adapt to emerging threats while maintaining the performance characteristics required for production workloads. + +## Attestation Verification Architecture + +The gateway implements a comprehensive attestation verification pipeline that validates multiple aspects of CVM integrity and authorization. This verification process is critical for maintaining the security guarantees that make confidential computing possible, ensuring that only legitimate, uncompromised workloads can access sensitive data and resources. + +### Quote Structure and Validation + +When a CVM requests registration, it must provide an attestation quote that includes cryptographic measurements of its software stack and execution environment. The gateway validates this quote through a series of checks that verify both the cryptographic integrity of the attestation and the policy compliance of the requesting CVM. + +The quote validation process includes verification of the cryptographic signature chain, validation of measurement values against expected baselines, and assessment of the freshness and uniqueness of the attestation evidence. This multi-step validation ensures that attestation quotes cannot be replayed, modified, or forged by attackers. + +### Real-time Security Monitoring + +Beyond initial registration, the gateway maintains ongoing verification of CVM security status through continuous monitoring of attestation evidence, network behavior, and system health metrics. This approach recognizes that security in confidential computing environments is not a one-time verification, but an ongoing process that must adapt to changing conditions and emerging threats. + +The monitoring system tracks multiple security indicators, including attestation refresh rates, cryptographic key rotation schedules, and behavioral anomalies that might indicate compromise or unauthorized access attempts. When security violations are detected, the gateway can automatically isolate affected CVMs and trigger security response procedures. + +## Authorization Contract Integration + +The gateway integrates with blockchain-based authorization contracts to ensure that technical validity is combined with policy compliance. This integration allows organizations to implement sophisticated access control policies that can be transparently audited and cryptographically verified by all participants in the confidential computing cluster. + +### Blockchain Verification Pipeline + +Authorization decisions are validated through integration with Ethereum-compatible smart contracts that maintain authoritative records of which CVMs are permitted to access specific resources. This approach provides transparency, auditability, and resistance to tampering that traditional centralized authorization systems cannot match. + +The verification pipeline includes real-time queries to authorization contracts, validation of transaction authenticity, and caching mechanisms that ensure performance while maintaining security guarantees. This design allows the gateway to make rapid authorization decisions while ensuring that all access grants can be independently verified and audited. + +### Continuous Compliance Monitoring + +The gateway continuously monitors compliance with authorization policies, detecting and responding to changes in authorization status, policy updates, and security incidents. This ongoing compliance monitoring ensures that access decisions remain current and accurate even as organizational policies and security requirements evolve. + +## Performance and Scalability Considerations + +Attestation verification is computationally intensive, requiring careful optimization to ensure that security operations do not become a bottleneck for cluster performance. The gateway implements several optimization strategies, including parallel verification pipelines, intelligent caching of verification results, and adaptive verification schedules that balance security requirements with performance needs. + +The system is designed to scale horizontally, allowing multiple gateway instances to share verification workloads while maintaining consistent security decisions across the entire cluster. This distributed approach ensures that attestation verification can keep pace with growing cluster sizes and increasing security requirements. \ No newline at end of file diff --git a/docs/security-research/gate/gate-cvm-registration.mdx b/docs/security-research/gate/gate-cvm-registration.mdx new file mode 100644 index 00000000..e18a9976 --- /dev/null +++ b/docs/security-research/gate/gate-cvm-registration.mdx @@ -0,0 +1,68 @@ +--- +title: "Gateway CVM Registration and Attestation" +description: "Secure registration process for confidential virtual machines with remote attestation and WireGuard network configuration" +--- + +# Gateway CVM Registration and Attestation + +CVM registration represents the cornerstone of trust establishment in confidential computing environments. Unlike traditional virtual machine deployment where trust is assumed based on administrative controls, confidential virtual machines must cryptographically prove their integrity before being granted access to any cluster resources. This process, known as remote attestation, creates a hardware-backed chain of trust that extends from the silicon level up through the hypervisor, operating system, and application layers. + +The dstack gateway's CVM registration process is designed around the principle that trust must be earned and continuously validated, not assumed. Every CVM that wishes to join the cluster must not only prove that it's running genuine, unmodified code inside a trusted execution environment, but also demonstrate that it has been explicitly authorized by the cluster's governance mechanisms. This dual requirement of technical validity and policy compliance ensures that only legitimate, secure workloads can participate in the confidential computing cluster. + +What sets dstack's approach apart is its integration of multiple security technologies into a seamless registration workflow. Remote attestation provides cryptographic proof of CVM integrity, WireGuard establishes encrypted communication channels, and blockchain-based authorization contracts ensure that access decisions are transparent and auditable. This layered security model creates multiple opportunities to detect and prevent unauthorized access attempts while maintaining operational simplicity for legitimate users. + +## Gateway CVM Registration Process + +a CVM, or confidential virtual machine, is a virtual machine that runs inside a trusted execution environment (TEE) such as Intel TDX, providing hardware-enforced isolation and cryptographic protection for its code and data—even from the host or hypervisor. in dstack, CVMs are the core compute units that participate in the secure cluster, and their integrity is critical for trustless operation between nodes. + +to ensure that only trusted CVMs can join and communicate within the gateway cluster, every CVM must go through a registration process. this process requires the CVM to prove its trustworthiness via remote attestation (demonstrating it is running genuine, unmodified code inside a TEE) and to establish a secure, encrypted network channel using wireguard tunnels. wireguard provides authenticated, high-performance VPN connections between the gateway and each registered CVM, ensuring that all traffic is protected from eavesdropping or tampering. + +this registration process is essential for enabling trustless synchronization and secure communication between nodes in the dstack gateway architecture—only CVMs that have passed attestation and are properly registered are allowed to participate in the cluster and exchange state or data. + +### Remote Attestation Verification + +remote attestation verification is a critical security step in the gateway's CVM registration process. its primary purpose is to ensure that only trusted, hardware-backed confidential virtual machines (CVMs) are allowed to join the cluster. this mechanism prevents unauthorized or potentially compromised VMs from gaining access to sensitive network resources, enforcing a strong trust boundary at the point of entry. + +conceptually, remote attestation is a cryptographic protocol where a CVM proves to the gateway that it is running genuine, unmodified code inside a trusted execution environment (TEE), such as Intel TDX. the CVM generates an attestation report (or "quote") that includes measurements of its software stack and environment, which are then cryptographically signed by the TEE hardware. this report serves as verifiable evidence of the CVM's integrity and identity. + +the gateway's [RegisterCvm RPC endpoint](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L12C1-L17C3) (see the `RegisterCvmRequest` and related types) is responsible for handling CVM registration requests. as part of this process, the endpoint requires the CVM to submit its attestation evidence. the gateway then performs a series of verification steps: + +- it validates the cryptographic signature of the attestation report to ensure it was produced by genuine TEE hardware. +- it checks the measurements and configuration values in the report against expected values, confirming that the CVM is running approved code and has not been tampered with. +- it verifies that the attestation is fresh and not a replay of an old or compromised report. + +in addition to these technical checks, the gateway also integrates with the KMS authorization system. using the built-in auth client, the gateway cross-references the attestation evidence with known KMS authorization contracts. this step ensures that the CVM is not only technically valid, but also explicitly authorized to join the cluster according to organizational policy. + +only after all these verification steps succeed does the gateway allow the CVM to complete registration and participate in the secure network. this layered approach to attestation and authorization is fundamental to maintaining the security and integrity of the gateway cluster. + +### WireGuard Network Configuration + +WireGuard is a modern, high-performance VPN protocol that provides secure, encrypted tunnels between network peers using state-of-the-art cryptography. In the dstack gateway architecture, WireGuard is used to establish private, authenticated connections between the gateway and registered confidential virtual machines (CVMs), ensuring that all traffic within the cluster is protected from eavesdropping and tampering. + +After a CVM successfully completes remote attestation and registration, the gateway allocates an IP address for the CVM from a configured address pool and generates a WireGuard peer configuration. This configuration includes the CVM's public key, the gateway's endpoint information, and the allowed IP ranges for secure communication. These parameters ensure that only authorized CVMs can participate in the cluster and that network isolation is strictly enforced. + +The WireGuard network settings—such as the interface, listen port, key material, and IP ranges—are defined in the gateway's configuration file. For a detailed example of these settings, see the [gateway.toml configuration](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml), specifically the `[core.wg]` section. This configuration governs how the gateway manages WireGuard peers, allocates client IPs, and maintains secure connectivity for all registered CVMs. + + + + the following diagram illustrates the CVM registration and secure network setup process: the confidential virtual machine (CVM) first requests attestation from the KMS, which provides the attestation evidence. the CVM then registers with the gateway, submitting its public key and attestation. the gateway verifies the attestation, checks application authorization with the KmsAuth contract, and upon confirmation, allocates a WireGuard IP and configures WireGuard peers. finally, the gateway returns the WireGuard and agent configuration to the CVM, which then establishes a secure WireGuard tunnel with the gateway. + + +```mermaid +sequenceDiagram + participant CVM + participant Gateway + participant KMS + participant Auth as "KmsAuth Contract" + + CVM->>KMS: Request attestation + KMS->>CVM: Provide attestation + CVM->>Gateway: RegisterCvm with public key + attestation + Gateway->>Gateway: Verify attestation + Gateway->>Auth: Check app authorization + Auth->>Gateway: Authorization confirmed + Gateway->>Gateway: Allocate WireGuard IP + Gateway->>Gateway: Configure WireGuard peers + Gateway->>CVM: Return WireGuard config + agent config + CVM->>Gateway: Establish WireGuard tunnel +``` \ No newline at end of file diff --git a/docs/security-research/gate/gate-implementation.mdx b/docs/security-research/gate/gate-implementation.mdx new file mode 100644 index 00000000..cd1d4b5a --- /dev/null +++ b/docs/security-research/gate/gate-implementation.mdx @@ -0,0 +1,70 @@ +--- +title: "Gateway Implementation Security Details" +description: "Detailed technical implementation of gateway security features, network protocols, and system architecture components" +--- + +# Gateway Implementation Security Details + +The implementation of dstack's gateway security features represents a careful balance between robust security guarantees and operational efficiency. Unlike academic security systems that can prioritize theoretical security over practical considerations, production confidential computing systems must deliver strong security while maintaining the performance, reliability, and usability characteristics required for real-world deployments. + +dstack's gateway implementation is built around the principle of secure by design, where security considerations are integrated into every aspect of the system architecture rather than being added as an afterthought. This approach ensures that security mechanisms are not just effective, but also efficient, maintainable, and resistant to the kinds of operational failures that can compromise security in production environments. + +The technical implementation encompasses multiple interconnected systems, including network protocol handlers, cryptographic verification engines, state management systems, and monitoring infrastructure. Each component is designed to fail securely, ensuring that system failures do not compromise the security guarantees that applications depend on. + +## Network Protocol Implementation + +The gateway implements multiple network protocols simultaneously, each optimized for different aspects of confidential computing communication requirements. This multi-protocol approach allows the system to optimize for different security and performance requirements while maintaining compatibility with existing network infrastructure. + +### TLS Protocol Handling + +The gateway's TLS implementation supports both termination and passthrough modes, allowing flexible deployment architectures that can adapt to different security requirements. TLS termination enables deep packet inspection and application-layer security controls, while passthrough mode preserves end-to-end encryption when required by compliance or security policies. + +The implementation uses rustls with the ring cryptographic provider, providing memory-safe cryptographic operations that are resistant to the buffer overflow and memory corruption vulnerabilities that have historically affected TLS implementations. This choice represents a significant improvement in security posture compared to traditional OpenSSL-based implementations. + +### WireGuard Integration + +WireGuard integration provides high-performance, authenticated VPN connections between the gateway and registered CVMs. The implementation includes custom peer management logic that automatically configures and maintains WireGuard tunnels based on CVM registration status and health monitoring results. + +The WireGuard implementation includes advanced features like automatic key rotation, peer health monitoring, and dynamic network configuration that adapts to changing cluster topology. These features ensure that network security remains robust even as CVMs are added, removed, or migrated within the cluster. + +## Security Protocol Implementation + +### Remote Attestation Processing + +The gateway implements comprehensive remote attestation processing that can handle multiple attestation formats and verification procedures. This flexibility is essential for supporting different hardware platforms and evolving attestation standards while maintaining consistent security guarantees. + +The attestation processing pipeline includes quote validation, measurement verification, and policy compliance checking. Each step is implemented with careful attention to timing attack resistance, ensuring that the verification process does not leak information about the contents of attestation evidence or internal security policies. + +### Certificate Management Systems + +Certificate management is implemented through an integrated system that handles the complete certificate lifecycle, from initial provisioning through renewal and revocation. The system supports multiple certificate authorities and validation methods, providing flexibility for different deployment scenarios and security requirements. + +The implementation includes advanced features like automated renewal, certificate transparency monitoring, and emergency revocation procedures that can respond rapidly to security incidents or policy changes. + +## Performance Optimization + +### Connection Pooling and Caching + +The gateway implements sophisticated connection pooling and caching mechanisms that optimize performance while maintaining security guarantees. These optimizations are particularly important for attestation verification, which can be computationally intensive and time-consuming. + +Caching strategies are designed to balance performance improvements with security requirements, ensuring that cached data cannot be used to bypass security controls or leak sensitive information about system state or configuration. + +### Async Processing Architecture + +The gateway uses an asynchronous processing architecture that maximizes throughput while maintaining low latency for critical security operations. This architecture allows the system to handle high connection volumes without compromising the responsiveness required for real-time security decisions. + +The async implementation includes careful resource management and backpressure handling that prevents resource exhaustion attacks and ensures stable performance under varying load conditions. + +## Error Handling and Recovery + +### Graceful Degradation + +The gateway is designed to degrade gracefully when faced with partial system failures or security incidents. This approach ensures that the system remains operational and secure even when individual components are compromised or unavailable. + +Graceful degradation includes fallback procedures for attestation verification, alternative authorization mechanisms, and emergency protocols that can maintain basic security guarantees even during significant system disruptions. + +### Security Incident Response + +The implementation includes comprehensive security incident response capabilities that can automatically detect, isolate, and respond to security violations. These capabilities are essential for maintaining security in dynamic environments where threats can emerge rapidly and evolve quickly. + +Incident response procedures are designed to minimize false positives while ensuring rapid response to genuine security threats, balancing operational stability with security responsiveness. \ No newline at end of file diff --git a/docs/security-research/gate/gate-load-balancing.mdx b/docs/security-research/gate/gate-load-balancing.mdx new file mode 100644 index 00000000..ff80f74e --- /dev/null +++ b/docs/security-research/gate/gate-load-balancing.mdx @@ -0,0 +1,88 @@ +--- +title: "Gateway Connection Strategies and Load Balancing" +description: "Advanced load balancing algorithms and connection management strategies for confidential virtual machine clusters" +--- + +# Gateway Connection Strategies and Load Balancing + +Load balancing in confidential computing environments presents unique challenges that go far beyond traditional traffic distribution. While conventional load balancers primarily focus on optimizing performance metrics like response time and throughput, confidential computing load balancers must also maintain cryptographic trust relationships, verify ongoing attestation status, and ensure that security guarantees are preserved across all connection routing decisions. + +The dstack gateway's connection management system represents a fundamental rethinking of how traffic should be distributed in security-critical environments. Traditional round-robin or least-connections algorithms are insufficient when each backend server (CVM) must be continuously verified for integrity and authorization. Instead, dstack implements intelligent selection algorithms that prioritize not just performance, but also the cryptographic health and attestation status of each CVM instance. + +What makes this approach particularly sophisticated is its integration of multiple data sources for routing decisions. The gateway doesn't just consider server load or response times - it evaluates WireGuard handshake freshness, attestation validity, authorization status, and real-time health metrics to make routing decisions that optimize both performance and security. This creates a dynamic, adaptive system that can respond to security events, hardware failures, and changing network conditions while maintaining the strict security guarantees required for confidential computing. + +## Gateway Connection Strategies and Load Balancing + +if you aren't familiar with the concept of a gateway in confidential computing, it's the component that acts as a secure entry point for network traffic destined for confidential virtual machines (CVMs) within a cluster. the gateway is responsible for authenticating, authorizing, and securely routing connections to the appropriate CVM instances, enforcing both network isolation and policy controls. + +connection strategies in this context refer to the algorithms and mechanisms the gateway uses to decide *which* CVM instance should handle a given incoming connection. this is especially important in environments where multiple CVMs are available for the same application or service, and the system must balance load, optimize performance, and maintain security guarantees. + +the dstack gateway implements a set of advanced connection management strategies to efficiently distribute traffic and maintain high availability: + +- **top-n selection**: the gateway tracks the most recent WireGuard handshake times for all registered CVMs. when a new connection request arrives, it sorts the available instances by handshake recency and selects the top N most recently active CVMs. this approach prioritizes instances that are known to be healthy and responsive, reducing connection latency and avoiding stale or disconnected peers. +- **direct instance selection**: for scenarios requiring deterministic routing (such as session stickiness or debugging), the gateway allows direct lookup and connection to a specific CVM instance by its unique identifier, bypassing the load balancer. +- **randomized fallback**: if the top-n selection yields no healthy candidates (e.g., all are stale or unreachable), or if the configuration disables top-n, the gateway falls back to random selection among all available CVMs, with additional health checks based on WireGuard handshake status to avoid routing to dead peers. +- **connection health monitoring**: the gateway continuously monitors the health of each CVM connection using WireGuard handshake timestamps and connection counters. instances that fail to respond or become stale are automatically removed or recycled according to configurable timeout policies. +- **certificate transparency monitoring**: to defend against certificate-based attacks, the gateway integrates with a certificate transparency (CT) monitoring system, ensuring that only certificates with known, authorized public keys are accepted for CVM connections. + +these strategies work together to provide robust, secure, and efficient connection management for confidential workloads, ensuring that only healthy, authorized CVMs receive traffic and that the system can adapt to failures or dynamic scaling events in real time. + +Below are several recommended connection management strategies available in the dstack gateway. Each approach is designed to address different operational and security needs, and can be selected or combined based on your deployment requirements: + +1. **Top-N Selection Strategy** + the primary connection strategy in the dstack gateway uses a top-n selection algorithm that prioritizes confidential virtual machine (CVM) instances based on recent WireGuard handshake times ([main_service.rs:286-335](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L286)). when a new connection request arrives, the gateway checks the latest handshake times for all CVMs associated with the requested application, sorts these instances by handshake elapsed time, and selects the top N most recently active instances (as configured by `connect_top_n`). this ensures that traffic is routed to peers that are known to be alive and responsive, minimizing latency and avoiding stale or unreachable instances. + + the algorithm for sorting and selecting the top N instances is implemented as follows ([main_service.rs:329-334](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6)): + + [See implementation in gateway/src/main_service.rs (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6): + + ```rust + instances.sort_by(|a, b| a.1.cmp(&b.1)); + instances.truncate(n); + Ok(instances + .into_iter() + .map(|(ip, _, counter)| AddressInfo { ip, counter }) + .collect()) + ``` + + if the top-n cache is still valid (i.e., not expired), the gateway reuses the cached selection for efficiency. if handshake data cannot be retrieved (for example, due to an error), the gateway logs a warning and falls back to random selection among available instances. if `connect_top_n` is set to 0, the system also defaults to random selection. for localhost development, a special case routes traffic directly to `127.0.0.1`. + + for implementation details, see [`select_top_n_hosts`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L286). + +2. **Direct Instance Selection** + sometimes you need to connect to a specific CVM instance instead of letting the gateway's load balancer decide. this is useful for debugging, session stickiness, or when deterministic routing is required. the dstack gateway enables this by allowing you to provide the unique identifier of a CVM instance; when you do, the gateway bypasses its normal load balancing and routes the connection directly to that instance. this gives you precise control over which CVM handles your request. + + the direct instance selection logic is implemented by checking for a specific instance ID and, if present, returning the corresponding connection details. see the implementation in [`main_service.rs` (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6). this mechanism ensures that applications or operators can always target a particular CVM when needed, without interference from the load balancer. + +3. **Fallback Strategies** + if the top-n selection does not return any healthy CVMs (for example, if all candidates are stale, unreachable, or if `connect_top_n` is set to 0), the gateway switches to a fallback strategy. + + [See fallback implementation in gateway/src/main_service.rs (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L301): + + ```rust + if n == 0 { + // fallback to random selection + return Ok(self.random_select_a_host(id).unwrap_or_default()); + } + ``` + + in this mode, the gateway randomly selects from all available CVMs, but before making a selection, it checks the WireGuard handshake status for each instance to verify health ([see implementation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L337C5-L350C1)). only CVMs with recent, valid handshakes are considered eligible, so traffic is never routed to dead or unresponsive instances even when falling back to random selection. + + +4. **connection health monitoring** + the gateway continuously monitors the health of each CVM instance by tracking WireGuard handshake timestamps and connection activity. if an instance is found to be stale—meaning its last handshake exceeds a configurable timeout—the gateway automatically recycles and removes it from the active pool. this recycling and removal process is logged (see [main_service.rs:454-485](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L454C7-L485C6)), ensuring visibility and auditability. after recycling, the WireGuard peer set is reconfigured to reflect the updated state, so only healthy, responsive CVMs are available for new connections. + + these health check and recycling behaviors are fully configurable in the gateway's toml configuration file, especially under the `[core.recycle]` section. for example: + ```toml + [core.recycle] + enabled = true + interval = "5m" + timeout = "10h" + node_timeout = "10m" + ``` + for a complete reference configuration, see the [gateway.toml example](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml). + you can adjust the recycling interval, timeouts, and enable/disable the feature as needed for your deployment. this automated health monitoring and recycling mechanism helps maintain a robust, reliable set of CVM endpoints without manual intervention. + +5. **Certificate Transparency Monitoring** + To defend against certificate-based attacks, the gateway integrates with a Certificate Transparency (CT) monitoring system. This system continuously checks CT logs for unauthorized certificate issuance and ensures that only certificates with known, authorized public keys are accepted for CVM connections. This provides an additional layer of protection against malicious or misissued certificates. + diff --git a/docs/security-research/gate/gate-notes.mdx b/docs/security-research/gate/gate-notes.mdx new file mode 100644 index 00000000..117a2754 --- /dev/null +++ b/docs/security-research/gate/gate-notes.mdx @@ -0,0 +1,36 @@ +--- +title: "Gateway Cryptographic Implementation and Security Notes" +description: "Comprehensive notes on cryptographic security implementation, TLS configuration, and security architecture principles in dstack gateway" +--- + +# Gateway Cryptographic Implementation and Security Notes + +The cryptographic foundation of dstack's gateway represents the culmination of modern secure communication protocols, specifically adapted for the unique requirements of confidential computing environments. Unlike traditional network security implementations that focus primarily on protecting data in transit, confidential computing gateways must also verify the integrity and authenticity of the computing environments themselves, creating a multi-layered security architecture that extends trust verification from the network layer down to the hardware level. + +dstack's cryptographic implementation is built around the principle of defense in depth, where multiple independent security mechanisms work together to provide comprehensive protection. This approach recognizes that confidential computing environments face threats not just from network attackers, but also from potentially compromised hosts, malicious hypervisors, and sophisticated supply chain attacks. By implementing multiple overlapping security controls, the system can maintain security even if individual components are compromised. + +The choice of cryptographic primitives and protocols in dstack reflects careful consideration of both current security requirements and future threat models. The implementation prioritizes algorithms and approaches that have been thoroughly analyzed by the cryptographic community, while also ensuring compatibility with hardware security features like Intel TDX and other trusted execution environments. + +## Cryptographic Security Implementation + +### TLS Configuration and Crypto Providers + +The gateway uses rustls with the ring cryptographic provider for all TLS operations. This choice represents a deliberate move away from OpenSSL toward more modern, memory-safe cryptographic implementations that are less susceptible to the buffer overflow and memory corruption vulnerabilities that have historically plagued TLS implementations. The ring cryptographic provider offers high-performance, constant-time implementations of cryptographic primitives, reducing the risk of timing-based side-channel attacks. + +Certificate generation leverages RA-TLS capabilities when running in TEE environments, with fallback to KMS-based certificate authority for self-signed certificates. RA-TLS (Remote Attestation Transport Layer Security) represents a significant advancement in certificate-based authentication, allowing certificates to embed cryptographic attestation evidence directly in their structure. This creates a unified authentication mechanism where traditional X.509 certificate verification is enhanced with hardware-backed attestation validation. + +### Proxy Security Architecture + +The gateway implements both TLS termination and TLS passthrough modes based on SNI analysis. This flexibility allows the system to adapt to different security requirements - TLS termination enables deep packet inspection and application-layer security controls, while TLS passthrough preserves end-to-end encryption when required by compliance or security policies. + +Connection handling includes comprehensive timeout management and secure connection lifecycle management. These mechanisms protect against resource exhaustion attacks, connection hijacking attempts, and other network-based attacks that could compromise the availability or security of the gateway service. + +## Notes + +This document covers the security architecture of the dstack gateway, which serves as the entry point for external traffic to applications running in Confidential Virtual Machines. The gateway provides comprehensive security through automated certificate management, secure cluster communication, remote attestation verification, and intelligent load balancing. The implementation uses industry-standard protocols like ACME, WireGuard, and mutual TLS authentication to ensure secure communication throughout the system. + +The configuration parameters mentioned in this document can be customized through the gateway configuration file, allowing operators to tune the security and performance characteristics according to their specific deployment requirements. This configurability is essential for adapting the gateway to different threat models, compliance requirements, and operational constraints while maintaining the core security guarantees that make confidential computing possible. + +The security model is built on the principle of zero trust, where every component must be authenticated and authorized before being granted access to the network. Remote attestation ensures that only genuine TEE instances can register with the gateway, while Certificate Transparency monitoring provides ongoing security assurance against certificate-based attacks. This comprehensive approach to security creates multiple opportunities to detect and prevent attacks while maintaining the usability and performance characteristics required for production deployments. + +The dstack gateway's security architecture represents a significant advancement in confidential computing infrastructure, providing the robust security guarantees needed for sensitive workloads while maintaining the operational simplicity required for widespread adoption. As confidential computing continues to evolve, the gateway's modular architecture and comprehensive security controls provide a solid foundation for addressing emerging threats and requirements. \ No newline at end of file diff --git a/docs/security-research/gate/gate-overview.mdx b/docs/security-research/gate/gate-overview.mdx new file mode 100644 index 00000000..f3686276 --- /dev/null +++ b/docs/security-research/gate/gate-overview.mdx @@ -0,0 +1,72 @@ +--- +title: "Gateway Security Overview" +description: "Comprehensive overview of dstack's secure gateway architecture with automated certificate management" +--- + +# Gateway Security Overview + +In confidential computing architectures, the gateway serves as the critical security perimeter - the trusted bridge between the external world and the confidential virtual machines (CVMs) operating within trusted execution environments. Unlike traditional network gateways that primarily route traffic, a confidential computing gateway must establish, verify, and maintain cryptographic trust relationships while ensuring that only authenticated and authorized entities can access the secure cluster. + +The dstack gateway represents a paradigm shift in secure network architecture, combining automated certificate lifecycle management with hardware-backed attestation verification. This creates a zero-trust security model where every connection, whether from external clients or internal CVMs, must be cryptographically verified before being granted access to confidential workloads. + +Understanding the gateway's role is fundamental to comprehending dstack's security model: it's not just a network entry point, but a comprehensive security orchestrator that manages identity, encryption, and access control for confidential computing environments. Every certificate issued, every attestation verified, and every connection established flows through carefully designed security protocols that maintain the integrity of the entire system. + +## Advanced Certificate Management + +The dstack gateway implements comprehensive certificate management through an integrated certbot system that handles automatic certificate provisioning and renewal using Let's Encrypt's ACME protocol. + +Certificate management in confidential computing goes far beyond traditional TLS certificates. In dstack's architecture, certificates serve multiple critical functions: they establish secure communication channels, verify the identity of CVMs through RA-TLS (Remote Attestation Transport Layer Security), and provide cryptographic evidence that can be audited and verified by third parties. The gateway's certificate management system is designed to handle these complex requirements while maintaining operational simplicity and security. + +The automated nature of dstack's certificate management eliminates human error and ensures consistent security posture across the entire cluster. By integrating directly with Let's Encrypt and DNS providers, the system can respond to security incidents, rotate certificates proactively, and maintain compliance with industry standards without manual intervention. + +### Certificate Lifecycle Management + +The gateway's certificate management system uses a dedicated CertBot struct that automatically handles the entire certificate lifecycle. The system runs in a continuous loop with configurable renewal intervals , executing post-renewal hooks when certificates are successfully updated.([certbot.rs#L44](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L44)). + +The system supports automatic account creation, certificate issuance, and renewal with configurable intervals. The renewal process is implemented as a background loop ([certbot.rs#L118](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L118)), which periodically checks certificate status and triggers renewal as needed. After a successful renewal, an optional post-renewal hook can be executed for custom actions, with errors and statuses logged for observability. + +### DNS-01 Challenge with Cloudflare Integration + +The certificate validation process uses DNS-01 challenges, leveraging Cloudflare's DNS API for automated record management. The integration is implemented via the `Dns01Client::new_cloudflare` method, which initializes the DNS-01 client with the configured Cloudflare zone ID and API token ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L76)). This enables the gateway to programmatically create and clean up TXT records required for ACME validation, ensuring seamless and secure certificate issuance. + +the system can automatically set CAA (Certificate Authority Authorization) records to enhance security, as implemented in [certbot/src/bot.rs#L61](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L61). + +### Automatic Renewal Process + +Certificates are automatically renewed based on configurable expiration thresholds . The renewal process includes timeout protection and hook execution for post-renewal tasks . The default configuration sets renewal intervals to 1 hour and renewal before expiration to 10 days . + +The gateway's certificate renewal logic is implemented as an automated process that periodically checks certificate validity and triggers renewal when the expiration threshold is reached. This is handled in the CertBot component, which logs each renewal check and invokes the ACME client to perform the renewal if needed ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L176)). The renewal interval and expiration threshold are fully configurable, ensuring certificates are always refreshed before expiry without manual intervention. + +the renewal process includes timeout protection and, if a post-renewal hook is configured, executes it using a shell command. the system logs when the hook is run, and if the hook fails (either by returning a non-zero status or by failing to execute), an error message is logged with details about the failure. + +```mermaid +sequenceDiagram + participant App + participant Gateway + participant Certbot + participant CF as "Cloudflare DNS" + participant LE as "Let's Encrypt" + participant CT as "CT Monitor" + + App->>Gateway: Request certificate + Gateway->>Certbot: Initialize certificate request + Certbot->>CF: Set CAA records + CF->>Certbot: CAA records configured + Certbot->>LE: Request certificate with DNS-01 challenge + LE->>Certbot: Provide challenge token + Certbot->>CF: Create TXT record with challenge + CF->>LE: DNS challenge verification + LE->>Certbot: Issue certificate + Certbot->>Gateway: Certificate ready + Gateway->>CT: Monitor certificate transparency logs + Gateway->>App: Certificate deployed + + Note over Certbot: Automatic renewal every hour + Certbot->>LE: Check certificate expiration + LE->>Certbot: Certificate status + alt Certificate expires in < 10 days + Certbot->>LE: Renew certificate + LE->>Certbot: New certificate issued + Certbot->>Gateway: Restart with new certificate + end +``` \ No newline at end of file diff --git a/docs/security-research/gate/gate-state-sync.mdx b/docs/security-research/gate/gate-state-sync.mdx new file mode 100644 index 00000000..e8f62f33 --- /dev/null +++ b/docs/security-research/gate/gate-state-sync.mdx @@ -0,0 +1,71 @@ +--- +title: "Gateway Cluster State Synchronization" +description: "Distributed state management and secure synchronization protocols for gateway clusters in dstack" +--- + +# Gateway Cluster State Synchronization + +State synchronization in confidential computing represents one of the most challenging aspects of distributed system design. Unlike traditional distributed systems where trust can be assumed among cluster members, confidential computing environments operate under a zero-trust model where every node must continuously prove its identity and integrity. The dstack gateway's state synchronization system addresses this challenge by implementing cryptographically secure protocols that enable multiple gateway nodes to maintain consistent cluster state while ensuring that only authenticated and authorized nodes can participate. + +The concept of "state" in this context encompasses far more than simple configuration data. It includes the complete knowledge of registered CVMs, their attestation status, cryptographic keys, network topology, health metrics, and authorization policies. This state must be synchronized across multiple gateway nodes to ensure high availability and load distribution, but this synchronization must never compromise the security guarantees that make confidential computing possible. + +What makes dstack's approach unique is its integration of hardware-backed attestation with traditional distributed consensus mechanisms. Each gateway node doesn't just sync data - it continuously validates the cryptographic identity of its peers, ensuring that compromised or malicious nodes cannot inject false state information or gain unauthorized access to sensitive cluster operations. + +## Gateway Cluster Topology and State Synchronization + +The dstack gateway supports distributed deployment through a cluster architecture where multiple gateway nodes synchronize their state to provide redundancy and load balancing. + +### Cluster State Management + +The gateway maintains its cluster state using a central `ProxyStateMut` structure ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L57)). This state includes information about other gateway nodes (`nodes`), registered applications (`apps`), CVM instances (`instances`), allocated network addresses, and additional internal tracking fields. By synchronizing this structured state across the cluster, the gateway ensures consistent knowledge of node membership, application registrations, and CVM instance assignments. + +each gateway node tracks other nodes in the cluster using a `GatewayNodeInfo` structure ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L49)), which includes the node's id, url, WireGuard peer information, and last-seen timestamp. + +### State Synchronization Protocol + +Gateway node state synchronization is achieved via secure RPC channels with mutual TLS authentication, ensuring both confidentiality and strong peer verification. The synchronization client (`SyncClient`) initiates connections to peer nodes using a purpose-built RPC client that strictly enforces certificate-based authentication and validates application identity ([sync client handshake and validation logic](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service/sync_client.rs#L31C1-L63C6)). +During the handshake, the client checks that the remote node presents a valid TLS certificate and that the application ID matches the expected cluster identity. If the app ID does not match, the connection is immediately rejected and a log entry records the error. +This rigorous validation mechanism ensures that only properly authenticated and authorized gateway nodes can participate in the state sync protocol, effectively blocking unauthorized or misconfigured nodes from joining the cluster. + +The state sync protocol is engineered for resilience, with built-in timeout protection and comprehensive error handling as detailed in the [sync client async logic](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service/sync_client.rs#L65C5-L85C6). When a node initiates a sync with a peer, it logs the attempt, enforces a timeout on the operation, and monitors for both timeout and RPC-level errors. If synchronization fails—due to timeout, network issues, or any other error—the system logs the failure with diagnostic details and continues operating, ensuring that cluster stability is not compromised by transient faults or misbehaving nodes. This design guarantees robust, fault-tolerant state propagation across the gateway cluster. + +### Node Recycling and Health Monitoring + +the gateway automatically removes ("recycles") stale nodes from the cluster based on their last-seen timestamp. as implemented in [main_service.rs#L439C4-L452C10](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L439C4-L452C10), the recycling logic iterates over all known nodes and checks if the time since their last_seen exceeds the configured node_timeout. if a node is considered stale and is not the current node itself, it is removed from the cluster state. this ensures that only healthy, recently active nodes remain in the cluster, improving reliability and preventing issues from unresponsive or disconnected peers. + + node health monitoring is configured in the gateway's toml file under the `[core.recycle]` section ([see gateway.toml](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml)), which sets parameters such as `interval`, `timeout`, and especially `node_timeout` (e.g., `node_timeout = "10m"`). the gateway tracks each node's last-seen timestamp and automatically recycles (removes) nodes that have not been seen within the `node_timeout` period. this mechanism is implemented in the gateway service using the `GatewayNodeInfo` structure and is part of the cluster state management logic, relying on the gateway's internal state synchronization and recycling packages. + +```mermaid +graph TD + subgraph "Gateway Cluster" + GW1["Gateway Node 1
10.4.0.1"] + GW2["Gateway Node 2
10.4.0.2"] + GW3["Gateway Node 3
10.4.0.3"] + end + + subgraph "CVM Network" + CVM1["CVM 1
10.4.1.10"] + CVM2["CVM 2
10.4.1.11"] + CVM3["CVM 3
10.4.1.12"] + end + + subgraph "State Synchronization" + Sync["Broadcast Sync
Every 10m"] + end + + GW1 <-->|"State Sync"| GW2 + GW2 <-->|"State Sync"| GW3 + GW3 <-->|"State Sync"| GW1 + + GW1 -->|"WireGuard"| CVM1 + GW1 -->|"WireGuard"| CVM2 + GW2 -->|"WireGuard"| CVM2 + GW2 -->|"WireGuard"| CVM3 + GW3 -->|"WireGuard"| CVM1 + GW3 -->|"WireGuard"| CVM3 + + Sync --> GW1 + Sync --> GW2 + Sync --> GW3 +``` + diff --git a/docs/security-research/gateway-security.mdx b/docs/security-research/gateway-security.mdx new file mode 100644 index 00000000..11c2faaa --- /dev/null +++ b/docs/security-research/gateway-security.mdx @@ -0,0 +1,279 @@ +--- +title: "Gateway Security Architecture" +description: "Secure ingress/egress with automated certificate management in dstack" +--- + +# dstack Gateway Security Architecture + +This document provides a comprehensive overview of the dstack gateway's security architecture, covering certificate management, cluster topology, CVM registration, and connection strategies. + +## Advanced Certificate Management + +The dstack gateway implements comprehensive certificate management through an integrated certbot system that handles automatic certificate provisioning and renewal using Let's Encrypt's ACME protocol. + +### Certificate Lifecycle Management + +The gateway's certificate management system uses a dedicated CertBot struct that automatically handles the entire certificate lifecycle. The system runs in a continuous loop with configurable renewal intervals , executing post-renewal hooks when certificates are successfully updated.([certbot.rs#L44](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L44)). + +The system supports automatic account creation, certificate issuance, and renewal with configurable intervals. The renewal process is implemented as a background loop ([certbot.rs#L118](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L118)), which periodically checks certificate status and triggers renewal as needed. After a successful renewal, an optional post-renewal hook can be executed for custom actions, with errors and statuses logged for observability. + +### DNS-01 Challenge with Cloudflare Integration + +The certificate validation process uses DNS-01 challenges, leveraging Cloudflare's DNS API for automated record management. The integration is implemented via the `Dns01Client::new_cloudflare` method, which initializes the DNS-01 client with the configured Cloudflare zone ID and API token ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L76)). This enables the gateway to programmatically create and clean up TXT records required for ACME validation, ensuring seamless and secure certificate issuance. + +the system can automatically set CAA (Certificate Authority Authorization) records to enhance security, as implemented in [certbot/src/bot.rs#L61](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L61). + +### Automatic Renewal Process + +Certificates are automatically renewed based on configurable expiration thresholds . The renewal process includes timeout protection and hook execution for post-renewal tasks . The default configuration sets renewal intervals to 1 hour and renewal before expiration to 10 days . + +The gateway's certificate renewal logic is implemented as an automated process that periodically checks certificate validity and triggers renewal when the expiration threshold is reached. This is handled in the CertBot component, which logs each renewal check and invokes the ACME client to perform the renewal if needed ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/certbot/src/bot.rs#L176)). The renewal interval and expiration threshold are fully configurable, ensuring certificates are always refreshed before expiry without manual intervention. + +the renewal process includes timeout protection and, if a post-renewal hook is configured, executes it using a shell command. the system logs when the hook is run, and if the hook fails (either by returning a non-zero status or by failing to execute), an error message is logged with details about the failure. + +```mermaid +sequenceDiagram + participant App + participant Gateway + participant Certbot + participant CF as "Cloudflare DNS" + participant LE as "Let's Encrypt" + participant CT as "CT Monitor" + + App->>Gateway: Request certificate + Gateway->>Certbot: Initialize certificate request + Certbot->>CF: Set CAA records + CF->>Certbot: CAA records configured + Certbot->>LE: Request certificate with DNS-01 challenge + LE->>Certbot: Provide challenge token + Certbot->>CF: Create TXT record with challenge + CF->>LE: DNS challenge verification + LE->>Certbot: Issue certificate + Certbot->>Gateway: Certificate ready + Gateway->>CT: Monitor certificate transparency logs + Gateway->>App: Certificate deployed + + Note over Certbot: Automatic renewal every hour + Certbot->>LE: Check certificate expiration + LE->>Certbot: Certificate status + alt Certificate expires in < 10 days + Certbot->>LE: Renew certificate + LE->>Certbot: New certificate issued + Certbot->>Gateway: Restart with new certificate + end +``` + +## Gateway Cluster Topology and State Synchronization + +The dstack gateway supports distributed deployment through a cluster architecture where multiple gateway nodes synchronize their state to provide redundancy and load balancing. + +### Cluster State Management + +The gateway maintains its cluster state using a central `ProxyStateMut` structure ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L57)). This state includes information about other gateway nodes (`nodes`), registered applications (`apps`), CVM instances (`instances`), allocated network addresses, and additional internal tracking fields. By synchronizing this structured state across the cluster, the gateway ensures consistent knowledge of node membership, application registrations, and CVM instance assignments. + +each gateway node tracks other nodes in the cluster using a `GatewayNodeInfo` structure ([see source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L49)), which includes the node's id, url, WireGuard peer information, and last-seen timestamp. + +### State Synchronization Protocol + +Gateway node state synchronization is achieved via secure RPC channels with mutual TLS authentication, ensuring both confidentiality and strong peer verification. The synchronization client (`SyncClient`) initiates connections to peer nodes using a purpose-built RPC client that strictly enforces certificate-based authentication and validates application identity ([sync client handshake and validation logic](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service/sync_client.rs#L31C1-L63C6)). +During the handshake, the client checks that the remote node presents a valid TLS certificate and that the application ID matches the expected cluster identity. If the app ID does not match, the connection is immediately rejected and a log entry records the error. +This rigorous validation mechanism ensures that only properly authenticated and authorized gateway nodes can participate in the state sync protocol, effectively blocking unauthorized or misconfigured nodes from joining the cluster. + +The state sync protocol is engineered for resilience, with built-in timeout protection and comprehensive error handling as detailed in the [sync client async logic](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service/sync_client.rs#L65C5-L85C6). When a node initiates a sync with a peer, it logs the attempt, enforces a timeout on the operation, and monitors for both timeout and RPC-level errors. If synchronization fails—due to timeout, network issues, or any other error—the system logs the failure with diagnostic details and continues operating, ensuring that cluster stability is not compromised by transient faults or misbehaving nodes. This design guarantees robust, fault-tolerant state propagation across the gateway cluster. + +### Node Recycling and Health Monitoring + +the gateway automatically removes ("recycles") stale nodes from the cluster based on their last-seen timestamp. as implemented in [main_service.rs#L439C4-L452C10](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L439C4-L452C10), the recycling logic iterates over all known nodes and checks if the time since their last_seen exceeds the configured node_timeout. if a node is considered stale and is not the current node itself, it is removed from the cluster state. this ensures that only healthy, recently active nodes remain in the cluster, improving reliability and preventing issues from unresponsive or disconnected peers. + + node health monitoring is configured in the gateway's toml file under the `[core.recycle]` section ([see gateway.toml](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml)), which sets parameters such as `interval`, `timeout`, and especially `node_timeout` (e.g., `node_timeout = "10m"`). the gateway tracks each node's last-seen timestamp and automatically recycles (removes) nodes that have not been seen within the `node_timeout` period. this mechanism is implemented in the gateway service using the `GatewayNodeInfo` structure and is part of the cluster state management logic, relying on the gateway's internal state synchronization and recycling packages. + +```mermaid +graph TD + subgraph "Gateway Cluster" + GW1["Gateway Node 1
10.4.0.1"] + GW2["Gateway Node 2
10.4.0.2"] + GW3["Gateway Node 3
10.4.0.3"] + end + + subgraph "CVM Network" + CVM1["CVM 1
10.4.1.10"] + CVM2["CVM 2
10.4.1.11"] + CVM3["CVM 3
10.4.1.12"] + end + + subgraph "State Synchronization" + Sync["Broadcast Sync
Every 10m"] + end + + GW1 <-->|"State Sync"| GW2 + GW2 <-->|"State Sync"| GW3 + GW3 <-->|"State Sync"| GW1 + + GW1 -->|"WireGuard"| CVM1 + GW1 -->|"WireGuard"| CVM2 + GW2 -->|"WireGuard"| CVM2 + GW2 -->|"WireGuard"| CVM3 + GW3 -->|"WireGuard"| CVM1 + GW3 -->|"WireGuard"| CVM3 + + Sync --> GW1 + Sync --> GW2 + Sync --> GW3 +``` + + +--- +## Gateway CVM Registration Process + +a CVM, or confidential virtual machine, is a virtual machine that runs inside a trusted execution environment (TEE) such as Intel TDX, providing hardware-enforced isolation and cryptographic protection for its code and data—even from the host or hypervisor. in dstack, CVMs are the core compute units that participate in the secure cluster, and their integrity is critical for trustless operation between nodes. + +to ensure that only trusted CVMs can join and communicate within the gateway cluster, every CVM must go through a registration process. this process requires the CVM to prove its trustworthiness via remote attestation (demonstrating it is running genuine, unmodified code inside a TEE) and to establish a secure, encrypted network channel using wireguard tunnels. wireguard provides authenticated, high-performance VPN connections between the gateway and each registered CVM, ensuring that all traffic is protected from eavesdropping or tampering. + +this registration process is essential for enabling trustless synchronization and secure communication between nodes in the dstack gateway architecture—only CVMs that have passed attestation and are properly registered are allowed to participate in the cluster and exchange state or data. + +### Remote Attestation Verification + +remote attestation verification is a critical security step in the gateway's CVM registration process. its primary purpose is to ensure that only trusted, hardware-backed confidential virtual machines (CVMs) are allowed to join the cluster. this mechanism prevents unauthorized or potentially compromised VMs from gaining access to sensitive network resources, enforcing a strong trust boundary at the point of entry. + +conceptually, remote attestation is a cryptographic protocol where a CVM proves to the gateway that it is running genuine, unmodified code inside a trusted execution environment (TEE), such as Intel TDX. the CVM generates an attestation report (or "quote") that includes measurements of its software stack and environment, which are then cryptographically signed by the TEE hardware. this report serves as verifiable evidence of the CVM's integrity and identity. + +the gateway's [RegisterCvm RPC endpoint](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L12C1-L17C3) (see the `RegisterCvmRequest` and related types) is responsible for handling CVM registration requests. as part of this process, the endpoint requires the CVM to submit its attestation evidence. the gateway then performs a series of verification steps: + +- it validates the cryptographic signature of the attestation report to ensure it was produced by genuine TEE hardware. +- it checks the measurements and configuration values in the report against expected values, confirming that the CVM is running approved code and has not been tampered with. +- it verifies that the attestation is fresh and not a replay of an old or compromised report. + +in addition to these technical checks, the gateway also integrates with the KMS authorization system. using the built-in auth client, the gateway cross-references the attestation evidence with known KMS authorization contracts. this step ensures that the CVM is not only technically valid, but also explicitly authorized to join the cluster according to organizational policy. + +only after all these verification steps succeed does the gateway allow the CVM to complete registration and participate in the secure network. this layered approach to attestation and authorization is fundamental to maintaining the security and integrity of the gateway cluster. + +### WireGuard Network Configuration + +WireGuard is a modern, high-performance VPN protocol that provides secure, encrypted tunnels between network peers using state-of-the-art cryptography. In the dstack gateway architecture, WireGuard is used to establish private, authenticated connections between the gateway and registered confidential virtual machines (CVMs), ensuring that all traffic within the cluster is protected from eavesdropping and tampering. + +After a CVM successfully completes remote attestation and registration, the gateway allocates an IP address for the CVM from a configured address pool and generates a WireGuard peer configuration. This configuration includes the CVM's public key, the gateway's endpoint information, and the allowed IP ranges for secure communication. These parameters ensure that only authorized CVMs can participate in the cluster and that network isolation is strictly enforced. + +The WireGuard network settings—such as the interface, listen port, key material, and IP ranges—are defined in the gateway's configuration file. For a detailed example of these settings, see the [gateway.toml configuration](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml), specifically the `[core.wg]` section. This configuration governs how the gateway manages WireGuard peers, allocates client IPs, and maintains secure connectivity for all registered CVMs. + + + + the following diagram illustrates the CVM registration and secure network setup process: the confidential virtual machine (CVM) first requests attestation from the KMS, which provides the attestation evidence. the CVM then registers with the gateway, submitting its public key and attestation. the gateway verifies the attestation, checks application authorization with the KmsAuth contract, and upon confirmation, allocates a WireGuard IP and configures WireGuard peers. finally, the gateway returns the WireGuard and agent configuration to the CVM, which then establishes a secure WireGuard tunnel with the gateway. + + +```mermaid +sequenceDiagram + participant CVM + participant Gateway + participant KMS + participant Auth as "KmsAuth Contract" + + CVM->>KMS: Request attestation + KMS->>CVM: Provide attestation + CVM->>Gateway: RegisterCvm with public key + attestation + Gateway->>Gateway: Verify attestation + Gateway->>Auth: Check app authorization + Auth->>Gateway: Authorization confirmed + Gateway->>Gateway: Allocate WireGuard IP + Gateway->>Gateway: Configure WireGuard peers + Gateway->>CVM: Return WireGuard config + agent config + CVM->>Gateway: Establish WireGuard tunnel +``` +--- + + +## Gateway Connection Strategies and Load Balancing + +if you aren't familiar with the concept of a gateway in confidential computing, it's the component that acts as a secure entry point for network traffic destined for confidential virtual machines (CVMs) within a cluster. the gateway is responsible for authenticating, authorizing, and securely routing connections to the appropriate CVM instances, enforcing both network isolation and policy controls. + +connection strategies in this context refer to the algorithms and mechanisms the gateway uses to decide *which* CVM instance should handle a given incoming connection. this is especially important in environments where multiple CVMs are available for the same application or service, and the system must balance load, optimize performance, and maintain security guarantees. + +the dstack gateway implements a set of advanced connection management strategies to efficiently distribute traffic and maintain high availability: + +- **top-n selection**: the gateway tracks the most recent WireGuard handshake times for all registered CVMs. when a new connection request arrives, it sorts the available instances by handshake recency and selects the top N most recently active CVMs. this approach prioritizes instances that are known to be healthy and responsive, reducing connection latency and avoiding stale or disconnected peers. +- **direct instance selection**: for scenarios requiring deterministic routing (such as session stickiness or debugging), the gateway allows direct lookup and connection to a specific CVM instance by its unique identifier, bypassing the load balancer. +- **randomized fallback**: if the top-n selection yields no healthy candidates (e.g., all are stale or unreachable), or if the configuration disables top-n, the gateway falls back to random selection among all available CVMs, with additional health checks based on WireGuard handshake status to avoid routing to dead peers. +- **connection health monitoring**: the gateway continuously monitors the health of each CVM connection using WireGuard handshake timestamps and connection counters. instances that fail to respond or become stale are automatically removed or recycled according to configurable timeout policies. +- **certificate transparency monitoring**: to defend against certificate-based attacks, the gateway integrates with a certificate transparency (CT) monitoring system, ensuring that only certificates with known, authorized public keys are accepted for CVM connections. + +these strategies work together to provide robust, secure, and efficient connection management for confidential workloads, ensuring that only healthy, authorized CVMs receive traffic and that the system can adapt to failures or dynamic scaling events in real time. + +Below are several recommended connection management strategies available in the dstack gateway. Each approach is designed to address different operational and security needs, and can be selected or combined based on your deployment requirements: + +1. **Top-N Selection Strategy** + the primary connection strategy in the dstack gateway uses a top-n selection algorithm that prioritizes confidential virtual machine (CVM) instances based on recent WireGuard handshake times ([main_service.rs:286-335](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L286)). when a new connection request arrives, the gateway checks the latest handshake times for all CVMs associated with the requested application, sorts these instances by handshake elapsed time, and selects the top N most recently active instances (as configured by `connect_top_n`). this ensures that traffic is routed to peers that are known to be alive and responsive, minimizing latency and avoiding stale or unreachable instances. + + the algorithm for sorting and selecting the top N instances is implemented as follows ([main_service.rs:329-334](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6)): + + [See implementation in gateway/src/main_service.rs (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6): + + ```rust + instances.sort_by(|a, b| a.1.cmp(&b.1)); + instances.truncate(n); + Ok(instances + .into_iter() + .map(|(ip, _, counter)| AddressInfo { ip, counter }) + .collect()) + ``` + + if the top-n cache is still valid (i.e., not expired), the gateway reuses the cached selection for efficiency. if handshake data cannot be retrieved (for example, due to an error), the gateway logs a warning and falls back to random selection among available instances. if `connect_top_n` is set to 0, the system also defaults to random selection. for localhost development, a special case routes traffic directly to `127.0.0.1`. + + for implementation details, see [`select_top_n_hosts`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L286). + +2. **Direct Instance Selection** + sometimes you need to connect to a specific CVM instance instead of letting the gateway's load balancer decide. this is useful for debugging, session stickiness, or when deterministic routing is required. the dstack gateway enables this by allowing you to provide the unique identifier of a CVM instance; when you do, the gateway bypasses its normal load balancing and routes the connection directly to that instance. this gives you precise control over which CVM handles your request. + + the direct instance selection logic is implemented by checking for a specific instance ID and, if present, returning the corresponding connection details. see the implementation in [`main_service.rs` (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L329C5-L335C6). this mechanism ensures that applications or operators can always target a particular CVM when needed, without interference from the load balancer. + +3. **Fallback Strategies** + if the top-n selection does not return any healthy CVMs (for example, if all candidates are stale, unreachable, or if `connect_top_n` is set to 0), the gateway switches to a fallback strategy. + + [See fallback implementation in gateway/src/main_service.rs (permalink)](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L301): + + ```rust + if n == 0 { + // fallback to random selection + return Ok(self.random_select_a_host(id).unwrap_or_default()); + } + ``` + + in this mode, the gateway randomly selects from all available CVMs, but before making a selection, it checks the WireGuard handshake status for each instance to verify health ([see implementation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L337C5-L350C1)). only CVMs with recent, valid handshakes are considered eligible, so traffic is never routed to dead or unresponsive instances even when falling back to random selection. + + +4. **connection health monitoring** + the gateway continuously monitors the health of each CVM instance by tracking WireGuard handshake timestamps and connection activity. if an instance is found to be stale—meaning its last handshake exceeds a configurable timeout—the gateway automatically recycles and removes it from the active pool. this recycling and removal process is logged (see [main_service.rs:454-485](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/gateway/src/main_service.rs#L454C7-L485C6)), ensuring visibility and auditability. after recycling, the WireGuard peer set is reconfigured to reflect the updated state, so only healthy, responsive CVMs are available for new connections. + + these health check and recycling behaviors are fully configurable in the gateway’s toml configuration file, especially under the `[core.recycle]` section. for example: + ```toml + [core.recycle] + enabled = true + interval = "5m" + timeout = "10h" + node_timeout = "10m" + ``` + for a complete reference configuration, see the [gateway.toml example](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/gateway.toml). + you can adjust the recycling interval, timeouts, and enable/disable the feature as needed for your deployment. this automated health monitoring and recycling mechanism helps maintain a robust, reliable set of CVM endpoints without manual intervention. + +5. **Certificate Transparency Monitoring** + To defend against certificate-based attacks, the gateway integrates with a Certificate Transparency (CT) monitoring system. This system continuously checks CT logs for unauthorized certificate issuance and ensures that only certificates with known, authorized public keys are accepted for CVM connections. This provides an additional layer of protection against malicious or misissued certificates. + + +--- + + +## Cryptographic Security Implementation + +### TLS Configuration and Crypto Providers + +The gateway uses rustls with the ring cryptographic provider for all TLS operations [28](#0-27) . Certificate generation leverages RA-TLS capabilities when running in TEE environments, with fallback to KMS-based certificate authority for self-signed certificates [29](#0-28) . + +### Proxy Security Architecture + +The gateway implements both TLS termination and TLS passthrough modes based on SNI analysis [30](#0-29) . Connection handling includes comprehensive timeout management and secure connection lifecycle management [31](#0-30) . + +## Notes + +This document covers the security architecture of the dstack gateway, which serves as the entry point for external traffic to applications running in Confidential Virtual Machines. The gateway provides comprehensive security through automated certificate management, secure cluster communication, remote attestation verification, and intelligent load balancing. The implementation uses industry-standard protocols like ACME, WireGuard, and mutual TLS authentication to ensure secure communication throughout the system. + +The configuration parameters mentioned in this document can be customized through the gateway configuration file [32](#0-31) , allowing operators to tune the security and performance characteristics according to their specific deployment requirements. + +The security model is built on the principle of zero trust, where every component must be authenticated and authorized before being granted access to the network. Remote attestation ensures that only genuine TEE instances can register with the gateway, while Certificate Transparency monitoring provides ongoing security assurance against certificate-based attacks. \ No newline at end of file diff --git a/docs/security-research/kms-security.mdx b/docs/security-research/kms-security.mdx new file mode 100644 index 00000000..366e1b50 --- /dev/null +++ b/docs/security-research/kms-security.mdx @@ -0,0 +1,19 @@ + +--- + +## DStack KMS References +**dstack code reference:** +- [ra-tls key derivation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/kdf.rs) +- [ra-tls attestation verification](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/attestation.rs) +- [ra-tls certificate management](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/cert.rs) + +## Public References +* [KMS authorization details](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L407) +* [NIST SP 800-56C Rev. 2](https://csrc.nist.gov/publications/detail/sp/800-56c/rev-2/final) +* ["Recommendation for Key Derivation Using Pseudorandom Functions"](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1.pdf) + +
+

+ Next Component: See how derived keys protect traffic in the Gateway security architecture. +

+
diff --git a/docs/security-research/kms/kms-audit-procedures.mdx b/docs/security-research/kms/kms-audit-procedures.mdx new file mode 100644 index 00000000..b3b56596 --- /dev/null +++ b/docs/security-research/kms/kms-audit-procedures.mdx @@ -0,0 +1,18 @@ +--- +title: "KMS Verification and Audit Procedures" +description: "How dStack KMS enables independent auditing, measurement validation, and cryptographic assurance." +--- + +## Verification and Audit Procedures + +Verification and audit are essential for maintaining trust in any key management system. dStack KMS is designed to be fully auditable, allowing security professionals and external parties to independently verify every step of the attestation and key derivation process. This section details how auditors can review attestation logic, validate measurements, and ensure that cryptographic operations are both correct and compliant. + +### Security Auditing + +Security auditors are encouraged to review the entire attestation and key derivation logic, including TDX quote validation, measurement whitelists, and event log replay ([attestation.rs#L422](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L422)). This ensures RTMR values genuinely reflect the execution path. Deterministic key derivation enables repeated audits and comparison of outputs with known inputs. + +### Measurement Validation + +Verification requires validation of five categories: MRTD (firmware), RTMR0 (hardware config), RTMR1 (kernel), RTMR2 (boot params), RTMR3 (application). The [attestation documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#22-determining-expected-mrs) details expected values and verification steps. Building the OS image from source and using dstack-mr to calculate measurements allows independent validation. + +> Auditability is a core value of dStack KMS. The next section explores how blockchain integration provides decentralized, transparent authorization and policy enforcement. diff --git a/docs/security-research/kms/kms-blockchain-integration.mdx b/docs/security-research/kms/kms-blockchain-integration.mdx new file mode 100644 index 00000000..86882384 --- /dev/null +++ b/docs/security-research/kms/kms-blockchain-integration.mdx @@ -0,0 +1,27 @@ +--- +title: "KMS Blockchain Integration" +description: "How dStack KMS leverages blockchain for decentralized authorization and policy enforcement." +--- + +## Blockchain Integration + +Blockchain integration is a defining feature of dStack KMS, enabling decentralized, transparent, and tamper-evident authorization for key management. By leveraging Ethereum-compatible smart contracts, dStack KMS enforces application-specific access controls, device restrictions, and upgrade policies directly on-chain. This approach provides a level of auditability and policy assurance that is unmatched by traditional KMS solutions. + +### Decentralized Authorization + +dStack KMS integrates with Ethereum-compatible blockchains for decentralized authorization. The [AppAuth contract](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/auth-eth/contracts/AppAuth.sol#L9) enforces application-specific access controls—validating allowed compose hashes, device restrictions, and upgrade policies. The KmsAuth contract maintains registries for allowed KMS instances, OS images, and configurations, supporting transparent, auditable policy enforcement. + +Authorization logic is enforced directly in the smart contract ([AppAuth.sol#L110](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/auth-eth/contracts/AppAuth.sol#L110)): application identity, compose hash, and device restrictions are all checked on-chain before key access is permitted. Owners can permanently disable upgrades for greater assurance. + +### Attestation Verification Pipeline + +Key provisioning is controlled by a strict attestation pipeline ([main_service.rs#L407](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L407)), which verifies: + +* TDX quote signature and measurement extraction +* Validation of all runtime measurements (MRTD, RTMR0–RTMR3), application metadata, and device IDs +* Integrity and authenticity of the VM configuration and OS image hash +* Aggregation of all attestation and config data into a `boot_info` structure +* Blockchain authorization via Auth smart contract +* Immediate denial and abort if any requirement fails + +> Blockchain integration in dStack KMS is not just a feature—it's a foundation for decentralized, transparent, and policy-driven security. The next section explores the security architecture that underpins these guarantees. diff --git a/docs/security-research/kms/kms-cert-manager.mdx b/docs/security-research/kms/kms-cert-manager.mdx new file mode 100644 index 00000000..df829737 --- /dev/null +++ b/docs/security-research/kms/kms-cert-manager.mdx @@ -0,0 +1,27 @@ +--- +title: "KMS Certificate Management and RA-TLS" +description: "How dStack KMS uses RA-TLS and custom X.509 extensions to embed attestation and enforce certificate trust." +--- + +## Certificate Management and RA-TLS + +Certificate management is a cornerstone of secure communication in dStack. The KMS implements Remote Attestation TLS (RA-TLS), embedding TDX quotes, event logs, application IDs, and usage policy as custom X.509 extensions. This approach ensures that every certificate is not only cryptographically valid, but also cryptographically bound to the attested state of the workload. + +### RA-TLS Implementation + +dStack KMS implements **Remote Attestation TLS (RA-TLS)** by embedding TDX quotes, event logs, application IDs, and usage policy as custom X.509 extensions ([cert.rs#L227](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/cert.rs#L227)). Custom OIDs and DER encoding enable cryptographic validation of both certificate authenticity and the underlying TEE state. + +Certificate signing requests include full attestation data, and only validated requests can obtain certificates ([ra-tls/src/cert.rs](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/cert.rs)). This guarantees that only fully attested workloads are eligible for trusted certificates. + +### Custom OID Extensions + +Special Object Identifiers (OIDs) embed security-critical data in X.509 certificates ([ra-tls/src/oids.rs](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/oids.rs)): + +* Quote data: `1.3.6.1.4.1.62397.1.1` +* Event logs: `1.3.6.1.4.1.62397.1.2` +* Application IDs: `1.3.6.1.4.1.62397.1.3` +* Certificate usage: `1.3.6.1.4.1.62397.1.4` + +These custom extensions allow any relying party to verify not only certificate validity, but also the full hardware-backed attestation state of the workload. + +> Certificate management in dStack KMS is inseparable from attestation. The next section explores the cryptographic implementation details that underpin this trust model. diff --git a/docs/security-research/kms/kms-implementation.mdx b/docs/security-research/kms/kms-implementation.mdx new file mode 100644 index 00000000..8d36b0ed --- /dev/null +++ b/docs/security-research/kms/kms-implementation.mdx @@ -0,0 +1,20 @@ +--- +title: "KMS Cryptographic Implementation Details" +description: "Technical deep dive into the cryptographic key hierarchy and secure key generation in dStack KMS." +--- + +## Implementation Details + +The security of dStack KMS is grounded in its cryptographic implementation. At the heart of the system is a hierarchical key structure, anchored by a hardware-rooted root CA and k256 ECDSA key. This architecture ensures that every key, certificate, and cryptographic operation is both isolated and auditable. + +### Cryptographic Key Hierarchy + +The KMS manages a hierarchical key structure ([main\_service.rs#L50](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L50)), anchored by a root CA certificate and a k256 ECDSA key. The root CA signs X.509 certificates, while the k256 key enables Ethereum-compatible signing and encryption. Application-specific keys are derived on demand, incorporating the app ID, instance ID, and purpose string ([main\_service.rs#L498](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L498)), ensuring strong isolation between workloads and cryptographic roles. + +### Secure Key Generation and Attestation + +The process begins with attestation verification ([ra-tls/src/attestation.rs#L321](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L321)). Each key is only issued if the requester's TDX quote is valid—meaning the signature, TCB status, and event logs all match expected measurements. If any aspect of attestation fails, key derivation is aborted. + +After verification, dstack KMS deterministically derives keys for different functions—such as disk encryption, environment encryption, and signing ([main\_service.rs#L515](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L515)). Each key is bound to a unique cryptographic context and never reused outside its intended purpose. + +> The cryptographic implementation is the technical foundation for all higher-level guarantees. The next section explores how dStack KMS supports verification and audit procedures for maximum transparency. diff --git a/docs/security-research/kms/kms-overview.mdx b/docs/security-research/kms/kms-overview.mdx new file mode 100644 index 00000000..edd66780 --- /dev/null +++ b/docs/security-research/kms/kms-overview.mdx @@ -0,0 +1,46 @@ +--- +title: "KMS Security Overview" +description: "Comprehensive introduction to dStack's decentralized, hardware-backed Key Management Service (KMS) and its security architecture." +--- + +# KMS Security Architecture + +**Component:** `dstack-kms` ([source](https://github.com/Dstack-TEE/dstack/tree/master/kms)) + +## Overview + +dStack's Key Management Service (KMS) is the backbone of cryptographic trust in the platform, providing decentralized, hardware-rooted key management for confidential workloads. Unlike traditional KMS solutions that rely on perimeter-based trust and static secrets, dStack KMS fuses Intel TDX hardware attestation, deterministic key derivation, and on-chain authorization to deliver provable, auditable, and scalable key management. + +## Architectural Synthesis + +dStack KMS represents a paradigm shift in key management: every cryptographic operation is tightly bound to attested hardware state and explicit authorization logic enforced by decentralized smart contracts. This eliminates the risks of centralized storage and static access control lists, ensuring that both key issuance and key usage are independently verifiable and cryptographically auditable. + +Instead of storing static secrets, all application and workload keys are derived on-demand from real-time attestation evidence. This enables robust horizontal scaling, flexible workload upgrades, and fine-grained policy governance, all without sacrificing cryptographic assurance. The result is a KMS architecture that delivers both strong confidentiality and transparent, externally verifiable integrity for distributed, cloud-native, and confidential workloads. + +## Why Decentralized Key Management? + +### Centralization Risks + +Traditional KMS solutions introduce single points of failure in both storage and trust. A compromise of the central KMS or its database can expose all managed keys. By contrast, dStack derives all application keys on demand, directly from hardware attestation data, eliminating the risk of key theft via database or infrastructure compromise. + +### dStack's Approach + +```mermaid +graph LR + subgraph "Traditional KMS" + C[Central KMS] + C --> K1[Key 1] + C --> K2[Key 2] + C --> K3[Key 3] + end + + subgraph "dstack KMS" + A1[Attestation 1] --> D1[Derived Key 1] + A2[Attestation 2] --> D2[Derived Key 2] + A3[Attestation 3] --> D3[Derived Key 3] + end +``` + +dStack KMS supports three security modes—**non-kms (ephemeral keys), local-key-provider (SGX-sealed keys), and full kms mode (blockchain-authorized, upgradeable keys)**. Each mode is described in the [KMS README overview](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#overview). + +> This overview sets the stage for a deep dive into each architectural and security component of dStack's KMS. Continue reading the following sections for a comprehensive understanding of how each layer contributes to the overall security model. diff --git a/docs/security-research/kms/kms-security-arch.mdx b/docs/security-research/kms/kms-security-arch.mdx new file mode 100644 index 00000000..3f497806 --- /dev/null +++ b/docs/security-research/kms/kms-security-arch.mdx @@ -0,0 +1,25 @@ +--- +title: "KMS Security Architecture Details" +description: "How dStack KMS uses hardware-backed key derivation and a robust trust model to secure key management." +--- + +## Security Architecture + +The security architecture of dStack KMS is built on a foundation of hardware-backed key derivation and a rigorous trust model. Every key is produced using HKDF-SHA256, seeded by unique hardware attestation data and domain-separating context. This ensures that each key is cryptographically unique, isolated, and never persisted outside the TEE. + +### Hardware-Backed Key Derivation + +At the core of dStack KMS is a hardware-rooted key derivation model. Each key is produced via **HKDF-SHA256**, seeded by unique hardware attestation data—specifically, TDX measurements and a domain-separating salt ("RATLS") plus context data (such as application identifiers). See the key derivation implementation in [ra-tls/src/kdf.rs#L19](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/kdf.rs#L19). + +Key derivation is hierarchical: parent keys can deterministically derive child keys for distinct application, instance, or usage contexts ([ra-tls/src/kdf.rs#L34](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/kdf.rs#L34)). This ensures every derived key is cryptographically unique and isolated—even if the same KMS instance manages thousands of workloads, each application's secrets remain independently protected. + +### Trust Model + +dStack KMS's security model is grounded in four main principles: + +1. **Hardware Root of Trust**: All keys are derived from CPU and runtime measurements ([MRTD, RTMR0–RTMR3](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L393)). +2. **No Key Persistence**: Keys are regenerated as needed from attestation data and are never stored outside TEE memory. +3. **Attestation Gated Access**: Only workloads that have passed strict TDX quote and event log validation ([ra-tls/src/attestation.rs#L291](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L291)) can access keys. +4. **Determinism**: The same measurements and context will always yield the same derived key—supporting reproducibility and scalable, stateless key management. + +> The security architecture is the backbone of dStack KMS. The next section explores the security properties and guarantees that result from this design. diff --git a/docs/security-research/kms/kms-security-props.mdx b/docs/security-research/kms/kms-security-props.mdx new file mode 100644 index 00000000..e83184c5 --- /dev/null +++ b/docs/security-research/kms/kms-security-props.mdx @@ -0,0 +1,25 @@ +--- +title: "KMS Security Properties and Guarantees" +description: "The cryptographic guarantees and attack resistance features of dStack KMS." +--- + +## Security Properties + +The security properties of dStack KMS are the result of careful cryptographic design and rigorous implementation. This section details the guarantees provided by the system, including confidentiality, integrity, authenticity, forward secrecy, and reproducibility, as well as the mechanisms that ensure robust resistance to real-world attacks. + +### Cryptographic Guarantees + +* **Confidentiality:** Application secrets are encrypted using X25519 key exchange and ChaCha20-Poly1305 AEAD, with keys derived for each context ([main\_service.rs#L501](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L501)). +* **Integrity:** Keccak256 hashes and ECDSA signatures (k256) protect all authenticated messages and keys ([crypto.rs#L29](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/crypto.rs#L29)). +* **Authenticity:** ECDSA P-256 signatures provide cryptographic proof of origin ([crypto.rs#L7](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/crypto.rs#L7)). +* **Forward Secrecy:** All keys are derived fresh from attestation at each boot—there are no long-lived static secrets. +* **Reproducibility:** Identical environments will derive identical keys, supporting stateless scale-out and recovery. + +### Attack Resistance + +dstack KMS is designed for robust resistance to real-world attacks: + +* **Key Extraction Prevention:** All keys exist only in TEE memory and are never written to disk in plaintext. +* **Replay Attack Mitigation:** Nonces and timestamps are included in attestation data ([attestation.rs#L47](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L47)), ensuring each attestation is unique and cannot be reused. +* **Rollback Protection:** Version checks in measurements ([attestation.rs#L345](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L345)) block attempts to use outdated or debug configurations. +* **Side Channel Hardening:** Cryptographic operations leverage constant-time code to reduce risk from timing attacks. diff --git a/docs/security-research/kms/kms-security.mdx b/docs/security-research/kms/kms-security.mdx new file mode 100644 index 00000000..a68ce5f3 --- /dev/null +++ b/docs/security-research/kms/kms-security.mdx @@ -0,0 +1,72 @@ +--- +title: "KMS Security: Performance, Best Practices, and Threat Model" +description: "Comprehensive overview of dStack KMS security posture, operational best practices, and threat model." +--- + +## KMS Security: Performance, Best Practices, and Threat Model + +dStack KMS is designed to deliver strong security guarantees while maintaining high performance and scalability. This section provides a comprehensive overview of the system's security posture, operational best practices, and the threat model it addresses. + +--- + +### Cryptographic Performance and Scalability + +dStack KMS leverages HKDF-SHA256 for key derivation, which is highly efficient and introduces minimal computational overhead. The architecture is optimized for concurrent and parallel key operations, ensuring that cryptographic guarantees are never compromised even under high load. + +To support large-scale deployments, KMS enables secure self-replication. New nodes can join the cluster by securely obtaining root keys from attested peers over authenticated channels ([see kms self-replication documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#kms-self-replication)). This approach allows for horizontal scaling while preserving the integrity of attestation-based trust across all nodes. + +--- + +### Security Best Practices + +**Key Usage:** +Applications should always request only the minimum set of keys required for their operation, following the principle of least privilege. Each derived key is purpose-scoped and must be used strictly for its intended cryptographic function. Regular key rotation is recommended to minimize risk. + +**Attestation Policy Management:** +Organizations are encouraged to define and enforce strict policies specifying allowed measurements, TCB (Trusted Computing Base) versions, and configuration parameters. These policies should be reviewed and updated regularly to adapt to evolving threats and maintain system robustness. + +**Monitoring and Auditing:** +dStack KMS logs all key derivation, attestation, and authorization events. Continuous monitoring of these logs is essential for detecting anomalous access patterns or policy violations, enabling rapid response to potential security incidents. + +--- + +### Integration and Application Security + +**Application Integration:** +For every trust relationship, applications must validate both the certificate chain and the attestation evidence provided by the KMS ([see KMS documentation: attestation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#attestation)). Signature chains should be verified end-to-end, from the message itself to the registered KMS root key, to ensure authenticity and integrity. + +**Network Security:** +All communications with the KMS are protected by RA-TLS channels with mutual attestation. This ensures that only trusted endpoints are able to exchange key material, preventing unauthorized access and man-in-the-middle attacks. + +--- + +### Threat Model and Security Boundaries + +dStack KMS is engineered to withstand a wide range of adversarial scenarios. The threat model assumes that attackers may gain control over hosts, networks, or other infrastructure components. However, the security of the system relies on the integrity of the TEE hardware, the attestation infrastructure, and the correct configuration of smart contracts. + +The system is specifically designed to: + +- Prevent unauthorized key access, even in the presence of compromised infrastructure +- Block attestation forgery and policy bypass attempts +- Ensure that only workloads with valid, hardware-backed attestation can access cryptographic material + +These guarantees hold as long as the underlying hardware and attestation mechanisms remain trustworthy and are properly configured. + +--- + +## DStack KMS References +**dstack code reference:** +- [ra-tls key derivation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/kdf.rs) +- [ra-tls attestation verification](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/attestation.rs) +- [ra-tls certificate management](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/cert.rs) + +## Public References +* [KMS authorization details](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/kms/src/main_service.rs#L407) +* [NIST SP 800-56C Rev. 2](https://csrc.nist.gov/publications/detail/sp/800-56c/rev-2/final) +* ["Recommendation for Key Derivation Using Pseudorandom Functions"](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1.pdf) + +
+

+ Next Component: See how derived keys protect traffic in the Gateway security architecture. +

+
diff --git a/docs/security-research/overview.mdx b/docs/security-research/overview.mdx new file mode 100644 index 00000000..e80562ee --- /dev/null +++ b/docs/security-research/overview.mdx @@ -0,0 +1,32 @@ +--- +title: "Security & Research Section" +description: "Deep technical analysis of dstack's security architecture for researchers and security engineers" +--- + +This section offers an in-depth security analysis of dstack's TEE implementation. For general information, refer to the [Core Concepts](/docs/concepts/overview) section. + +## For Security Researchers + +dstack is built on a foundation of hardware-enforced security primitives. This section provides detailed technical analysis of each security-critical component, including: + +- **Source code references** with direct links to implementation +- **Cryptographic protocol analysis** and trust boundaries +- **Attestation flow diagrams** and verification procedures +- **Key management architecture** and secure storage mechanisms + +## Core Security Components + + + + Remote attestation implementation using Intel TDX hardware primitives + + + Virtual Machine Manager security boundaries and isolation guarantees + + + Secure ingress/egress with automated certificate management + + + Decentralized key management with hardware-backed secure storage + + \ No newline at end of file diff --git a/docs/security-research/security-model-lib/sec-mod-ring.mdx b/docs/security-research/security-model-lib/sec-mod-ring.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/security-research/security-model.mdx b/docs/security-research/security-model.mdx new file mode 100644 index 00000000..fc9f0a3e --- /dev/null +++ b/docs/security-research/security-model.mdx @@ -0,0 +1,99 @@ +--- +title: "Cryptography" +description: "Complete reference for cryptographic primitives, libraries, and security mechanisms in dStack" +--- + +# Cryptographic Security Model + +**Overview:** The dStack framework leverages Intel TDX’s hardware protections alongside a suite of vetted cryptographic libraries to secure data in use, in transit, and at rest. Running applications inside a TDX Trusted Domain (TD) means even a privileged host or hypervisor cannot directly access the app’s memory or secrets. Intel TDX enforces hardware memory encryption: each TD’s memory is encrypted with a unique key generated by the CPU and stored internally (lost on reset), so plaintext memory is never exposed to the host. On top of this foundation, dStack employs strong cryptographic primitives to manage keys, encrypt sensitive data, and authenticate communication. All chosen algorithms and libraries are high-assurance and industry-proven, ensuring the TEE’s security model remains robust against modern threats. Below, we detail each cryptographic component, the guarantees it provides, and how it integrates into dStack’s TDX-based architecture (covering Remote Attestation TLS, key management, and sealed data handling). + +## **`ring` – Core Cryptographic Primitives** + +The *ring* library is the cornerstone for many cryptographic operations in dStack. It provides a safe, fast implementation of essential algorithms (symmetric ciphers, hash functions, signature schemes, etc.), largely drawing from BoringSSL’s battle-tested primitives. In practice, *ring* delivers constant-time, memory-safe implementations of algorithms like AES, SHA-2, HMAC, RSA, and ECDH/ECDSA, optimized in assembly for performance and security. By using *ring*, dStack benefits from *ring*’s rigorous testing and optimization process – ensuring cryptographic operations are correct and side-channel resistant. + +**Integration:** In dStack, *ring* serves as the cryptographic backbone. It underpins the TLS stack (via rustls) by handling low-level cryptography such as the AES-GCM cipher, X25519 elliptic-curve Diffie–Hellman, and HMAC-based key derivation during handshakes. It is also likely used for random number generation (leveraging a secure OS entropy source) and any signature verification needed (for example, verifying Intel’s attestation signatures or certificates). By relying on *ring*, dStack avoids unsafe or outdated cryptography – only modern, vetted algorithms are enabled. This library’s focus on a “safe, fast, small crypto” core aligns with dStack’s security-first approach, minimizing both the attack surface and the chance of misimplementation. Overall, *ring* reinforces the correctness and reliability of every cryptographic operation inside the TEE. + +## **`rustls` – Secure TLS with Remote Attestation** + +dStack uses *rustls* as its TLS library to secure communications to and from the TEE. Rustls is a modern TLS 1.2/1.3 implementation in Rust that emphasizes strong defaults and avoids legacy vulnerabilities. By design, rustls only offers high-grade ciphers and requires no insecure configuration, providing state-of-the-art cryptographic security out of the box. This means dStack’s TLS channels benefit from protocols like TLS 1.3, forward secrecy (ephemeral ECDH key exchanges), and robust cipher suites (e.g. AES-GCM and ChaCha20-Poly1305) with no support for obsolete algorithms. The entire stack is memory-safe, eliminating many classes of TLS vulnerabilities stemming from memory errors. + +**Integration (RA-TLS in dStack):** Critically, dStack integrates *rustls* with **Remote Attestation TLS (RA-TLS)** to authenticate the TEE itself to clients. In a traditional TLS handshake, the server presents an X.509 certificate signed by a CA. dStack instead uses an attestation-backed certificate: when a TEE instance starts, it generates a fresh (ephemeral) keypair **inside the enclave** and includes the new public key in its TDX attestation quote. The attestation quote (signed by Intel’s attestation service) is then embedded into an X.509 certificate which is presented during the TLS handshake. This design eliminates any need to provision long-term private keys to the enclave. A remote client (or dStack gateway) connecting over TLS can extract the quote from the certificate, verify it against Intel’s attestation certs, and thereby trust that the TLS public key truly belongs to a genuine TDX enclave with an approved measurement. Once the quote is validated, the client knows it is talking to an attested dStack TD and can proceed to establish the TLS channel. All standard TLS guarantees (encryption, integrity, perfect forward secrecy) then apply to the connection, with the added assurance that one endpoint is a trusted enclave. + +Using rustls to implement RA-TLS means this complex process is handled with high-level Rust safety and *ring*’s cryptography. For example, rustls (with *ring*) will perform the TLS 1.3 handshake using the enclave’s ephemeral key, negotiate an AES-GCM session key, and then encrypt all traffic to the enclave. The result is a secure channel where both confidentiality and endpoint authenticity (via attestation) are guaranteed. By adopting RA-TLS, dStack ensures that secret data can be sent into a TDX enclave only after verifying the enclave’s identity, embodying a strong **zero-trust** posture toward the host and network. The use of rustls further reinforces reliability: it has no unsafe code and is widely audited, giving researchers confidence that the TLS/attestation integration in dStack is sound and free from common pitfalls. + +## **`sodiumbox` – Sealed Box Encryption for Secrets** + +dStack handles sensitive user data (like environment variables, API keys, etc.) via an *Encrypted Environment Variables* mechanism to ensure the host never sees them in plaintext. The `sodiumbox` library underpins this feature. **SodiumBox** is a pure-Rust implementation of libsodium’s **Sealed Boxes**, which provide anonymous public-key encryption of messages. Under the hood, sodiumbox uses well-regarded NaCl primitives: Curve25519 (X25519) for elliptic-curve key exchange, XSalsa20-Poly1305 for symmetric authenticated encryption, the HSalsa20 function and BLAKE2 hash for deriving sub-keys. These algorithms collectively allow one to encrypt a message such that only the holder of a designated private key can decrypt it, while providing authenticity (the ciphertext cannot be altered undetected) even if the sender remains anonymous. The use of XSalsa20-Poly1305 (a 256-bit Salsa20 stream cipher with a Poly1305 MAC) ensures high performance and strong security, as pioneered by DJB’s NaCl library. + +**Integration:** In dStack, each TEE (CVM) generates an X25519 keypair internally, and the public key is made available for secret injection. When a user deploys an application, any secret environment variables are encrypted **client-side** using the enclave’s public key (via sodiumbox’s seal function). The ciphertext is then passed to the platform (or included in the deployment manifest) without ever revealing the secret to the host or dStack control plane. Upon startup, the enclave uses its X25519 private key to **open** (decrypt) these sealed boxes and retrieve the original secret values, which are then provided to the application. This workflow is explicitly documented: *“The environment variables will be encrypted on the client side and decrypted in the CVM before being passed to the containers.”*. Even if an attacker intercepts or dumps the host’s storage, the sealed secrets remain unintelligible without the enclave’s private key. + +This mechanism effectively implements **sealed data handling** at the application level – secrets are *sealed* to the enclave’s identity key. Key management is straightforward and secure: the X25519 private key never leaves the TEE and need not be persisted (a new keypair can be generated for each deployment or enclave reboot). Because sodiumbox is a pure-Rust library (with no C dependencies) created as a drop-in replacement for sodiumoxide’s sealed box API, it inherits libsodium’s strong security model while fitting dStack’s all-Rust, no-unsafe ethos. The result is a highly reliable system for secret management: even without a hardware “seal key”, dStack ensures sensitive data is always encrypted with state-of-the-art public-key cryptography before crossing the TEE boundary. + +## **`k256` – High-Assurance secp256k1 Elliptic Curve** + +dStack includes the `k256` library to handle cryptography on the secp256k1 elliptic curve, which is widely used in blockchain and cryptographic applications (for ECDSA signatures and key agreements). The *k256* crate is a pure Rust implementation of secp256k1 from the RustCrypto project, designed for security and correctness. It was developed by cryptography engineers as a high-quality alternative to C libraries, featuring constant-time arithmetic and extensive test vectors. The library reuses and adapts well-vetted code (e.g., leveraging techniques from Bitcoin’s secp256k1 library, like endomorphism-based acceleration) to achieve excellent performance without sacrificing safety. By being memory safe and avoiding FFI, k256 eliminates entire classes of vulnerabilities (such as buffer overflows or misused pointers) while performing complex elliptic-curve math. + +**Integration:** While the core dStack framework is agnostic to specific applications, having k256 available means the TEE can securely handle operations involving secp256k1 keys – for example, managing an Ethereum account’s private key, signing transactions, or participating in blockchain consensus from within the enclave. The presence of k256 signals that dStack’s security model extends to cryptocurrency use-cases: any secp256k1 private keys can be kept inside the TDX enclave, and all ECDSA signatures or ECDH exchanges on that curve are done with no exposure to the host. This is particularly relevant given dStack’s origins with Phala Network and other blockchain contributors – secp256k1 is the curve behind Bitcoin, Ethereum, and many other systems. Using k256 gives dStack high confidence in these operations: the implementation is the product of many expert contributors aiming to “produce a high-quality secp256k1 library”. It has been audited through community usage and is constantly updated to reflect best practices in elliptic-curve cryptography. In summary, any component of dStack or enclave application that uses secp256k1 benefits from k256’s strong guarantees of correctness and security, ensuring that cryptographic keys remain safe and cryptographic proofs (signatures) are computed correctly under the hood. + +## **`AES-GCM` – Authenticated Data Encryption** + +For symmetric encryption needs, dStack leans on the AES-GCM algorithm – a NIST-approved mode of AES encryption that provides authenticated encryption with associated data. AES-GCM combines the AES 128/256-bit block cipher (for confidentiality) with the Galois/Counter Mode of operation and a built-in Galois Message Authentication Code (for integrity). This means that when dStack encrypts any payload with AES-GCM, the output ciphertext is not only scrambled (unreadable without the key) but also tagged with an authentication code; any modification to the ciphertext or associated metadata will be detected upon decryption. The strength of AES-GCM is well-regarded: it’s a standard cipher for TLS (HTTP/2, HTTP/3 use it), VPNs, and storage encryption, known for its performance and security robustness. NIST’s recommendation highlights GCM as a robust mode for block ciphers, suitable for high-throughput authenticated encryption needs. + +**Integration:** In the dStack security architecture, AES-GCM is used wherever bulk data needs to be symmetrically encrypted. One primary use is within rustls TLS sessions – e.g., dStack’s TLS termination and RA-TLS channels typically use AES-128-GCM or AES-256-GCM cipher suites to encrypt tunnelled data. Additionally, if dStack ever needs to encrypt data at rest (for example, encrypting a file or container image before storing it on untrusted disk), it would employ AES-GCM to protect that data. In doing so, a random 96-bit IV and a symmetric key (derived or generated inside the enclave) are used to encrypt the plaintext and produce a ciphertext + 128-bit authentication tag. Even if an attacker retrieved the encrypted blob, without the key they cannot decrypt it; and any tampering with the ciphertext would render the tag invalid, preventing undetected modifications. + +**Key Management:** Symmetric keys for AES-GCM are managed within the TEE context. They may be derived from a higher-level secret or agreement – for instance, the TLS handshake (via *ring* and rustls) derives session keys using HKDF and hands them to AES-GCM for packet encryption. In other scenarios, dStack could generate a random key (using *ring*’s CSPRNG) for file encryption; that key could itself be protected by the enclave (possibly exported only under encryption via sodiumbox or wrapped with an attestation process if it needs to leave). Typically, these keys are ephemeral or enclave-bound: for example, TLS session keys last only for the session and are never written to disk, and any long-term symmetric key would be stored encrypted under an enclave-held key. By using AES-GCM, dStack aligns with industry best practices — this cipher is not only highly efficient on modern CPUs (with AES-NI and PCLMULQDQ instruction support) but also vetted by the cryptographic community. The result is that dStack’s data encryption layer is both **secure and performant**, ensuring high throughput encryption without sacrificing security guarantees. + +## **Robustness and Best-Practice Assurance** + +Collectively, these cryptographic components form a layered security model that is resilient against a wide range of threats. Intel TDX provides a hardware root of trust (enforcing memory encryption and secure boot measurements), while Remote Attestation and RA-TLS link that trust to network connections, and high-level encryption schemes protect data flowing in and out of the enclave. Every cryptographic primitive in use – from the X25519 and XSalsa20 of sodiumbox to the secp256k1 and AES-GCM implementations – reflects community-vetted, modern best practices. Notably, dStack avoids weak algorithms and eschews any “roll-your-own” crypto; it relies on proven libraries like *ring* and RustCrypto crates, which have undergone scrutiny. By focusing on pure-Rust or carefully vetted code, dStack reduces the risk of memory safety bugs and integrates smoothly with the TEE threat model (minimizing reliance on the untrusted host). + +**Key management** is handled with a principle of least privilege and ephemerality: ephemeral keys (for TLS and attestation) mean there are no long-lived private keys to protect on disk, and secrets intended for the enclave are always encrypted in transit (using the enclave’s public key or TLS channel). If persistent storage of secrets is required, dStack would seal them by encryption tied to the enclave’s identity or a user-provided passphrase, ensuring that even if data is saved outside the enclave, it remains protected by strong cryptography. The framework’s reliance on primitives like AES-GCM for any such storage guarantees both confidentiality and integrity of sealed data. + +In summary, the dStack cryptographic security model is built on **robust, high-assurance tools** that complement the guarantees of Intel TDX. By using these well-known libraries and algorithms, dStack instills confidence that data and communications are protected to the highest standards. Security researchers will recognize that each component – *ring*, rustls (with RA-TLS), sodiumbox, k256, AES-GCM – has been chosen precisely because it upholds correctness and soundness under scrutiny. This deliberate design ensures that dStack’s confidentiality and integrity promises in a TDX environment stand on a firm, industry-best foundation, without introducing undue risk or weak links in the cryptographic chain. + +**Online Source References:** + +1. Dstack Encrypted Env Vars – *DStack Documentation* ([GitHub source](https://github.com/Dstack-TEE/dstack)) + +2. Rustls Security Overview – [*Rustls Docs*](https://docs.rs/rustls/latest/rustls/#:~:text=%C2%A7Rustls%20,library) + +3. Intel TDX RA-TLS Design – *Intel® TDX Documentation* ([Download PDF](https://cdrdv2-public.intel.com/733585/tdx-virtual-firmware-design-guide-rev-004-20231206.pdf#:~:text=RA,report%20data%20and%20TD%20quote)) + +4. SodiumBox Crate Info – [Lib.rs (Kevin Wang)](https://lib.rs/crates/sodiumbox#:~:text=The%20implementation%20uses%20modern%2C%20well,Rust%20cryptographic%20libraries) + +5. k256 crate announcement – [Tony Arcieri, Iqlusion Blog](https://iqlusion.blog/k256-crate-pure-rust-projective-secp256k1-library) + +6. NIST GCM Recommendation – [*NIST SP 800-38D (2007)*](https://csrc.nist.gov/pubs/sp/800/38/d/final#:~:text=This%20Recommendation%20specifies%20the%20Galois%2FCounter,approved%20symmetric%20key%20block%20cipher) + +7. ring Cryptography Library – [docs.rs: safe, fast, small crypto using BoringSSL primitives](https://docs.rs/fedimint-ring/latest/ring/#:~:text=Safe%2C%20fast%2C%20small%20crypto%20using,Rust%20with%20BoringSSL%E2%80%99s%20cryptography%20primitives) + + +## Source Code References + +This article is based on the following key modules and scripts from the [DStack codebase](https://github.com/Dstack-TEE/dstack): + +- [`ra-tls/src/cert.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/cert.rs): + Implements X.509 certificate generation, custom extension embedding (TDX quotes, event logs, app IDs), and certificate signing logic for RA-TLS. + +- [`ra-tls/src/kdf.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/kdf.rs): + Provides the HKDF-based key derivation framework, including context separation and domain-specific key generation. + +- [`ra-tls/src/attestation.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/ra-tls/src/attestation.rs): + Handles TDX quote processing, attestation report generation, and integration with Intel DCAP QVL for quote verification. + +- [`sodiumbox/src/lib.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/sodiumbox/src/lib.rs): + Pure Rust implementation of libsodium-compatible sealed box encryption, using X25519 and XSalsa20-Poly1305. + +- [`kms/src/crypto.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/src/crypto.rs): + Core cryptographic operations for the Key Management System, including key derivation, ECDSA/secp256k1 signing, and hash utilities. + +- [`gateway/src/main.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/gateway/src/main.rs): + Main entry point for the dstack gateway, orchestrating authentication, certificate validation, and secure communication. + +- [`Cargo.toml`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/Cargo.toml): + Project manifest listing cryptographic dependencies (e.g., ring, rustls, sodiumoxide), feature flags, and build configuration. + +For operational security best practices, refer to the [deployment documentation](/docs/getting-started/deploying-applications). +For a detailed overview of system architecture, see the [infrastructure documentation](/docs/concepts/architecture). + +For further exploration, consult the [DStack GitHub repository](https://github.com/Dstack-TEE/dstack) and review the latest code for updates and implementation details. diff --git a/docs/security-research/tdx-att/tdx-implementation.mdx b/docs/security-research/tdx-att/tdx-implementation.mdx new file mode 100644 index 00000000..e61afc9f --- /dev/null +++ b/docs/security-research/tdx-att/tdx-implementation.mdx @@ -0,0 +1,33 @@ +--- +title: "TDX Cryptographic Implementation Details" +description: "Technical deep dive into the cryptographic primitives and implementation details of dStack's TDX attestation." +--- + +## Cryptographic Implementation Details + +### Hash Algorithm Support + +The attestation layer supports a full range of cryptographic hash algorithms for report data binding, as implemented in [`attestation.rs#L33`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L33). By default, `sha512` is used, but options include `sha256`, `sha384`, all SHA-3 variants, Keccak, and a `raw` mode for direct data binding. Every report data input is prefixed with a content tag (e.g., `kms-root-ca`, `ratls-cert`, `app-data`), ensuring context-specific and unambiguous measurements. This allows applications to select the most suitable hash algorithm, while maintaining interoperability and high security. + +The flexibility in hash algorithm selection is crucial for supporting a wide range of cryptographic policies and interoperability requirements. By allowing applications to choose the most appropriate algorithm, dStack ensures both forward compatibility and robust security. + +### Key Derivation Security + +All application keys are deterministically derived from hardware-sealed root keys, using application-specific identifiers for cryptographic isolation between tenants. The guest agent’s [`get_key`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150C1-L239C2) RPC method implements this: a root ECDSA key derives per-application keys by path, then signs the derived public key and usage context. This signature chain allows independent verification that every derived key is both valid and bound to the right application, so that only trusted code can use it. + +This approach to key derivation ensures that cryptographic material is never shared across tenants or applications, providing strong isolation and minimizing the risk of key compromise. + +## Notes + +dStack’s TDX attestation provides enterprise-grade security through hardware-rooted trust, complete measurement chains, and rigorous verification at every level. The platform’s guarantees rest on Intel TDX hardware, robust cryptographic construction, and careful, modular validation of all trust boundaries. This design enables flexible deployment for a range of use cases—while ensuring uncompromising security properties wherever it’s used. + +## References + +- [Intel TDX Module 1.5 Specification](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html) +- [dstack Attestation Design Doc](https://github.com/Dstack-TEE/dstack/blob/master/attestation.md) + +
+

+ Next Component: Learn how attestation integrates with the VMM security architecture. +

+
diff --git a/docs/security-research/tdx-att/tdx-integration-review.mdx b/docs/security-research/tdx-att/tdx-integration-review.mdx new file mode 100644 index 00000000..9d314822 --- /dev/null +++ b/docs/security-research/tdx-att/tdx-integration-review.mdx @@ -0,0 +1,30 @@ +--- +title: "TDX Integration Security and Guest Agent" +description: "How dStack integrates TDX attestation into real-world deployments, focusing on the guest agent and KMS workflows." +--- + +## Integration Security + +How the Guest Agent Operates + + +### Guest Agent Security + +When we refer to a "guest agent" in the context of dstack and TDX attestation, we mean a dedicated system process running inside the confidential virtual machine (CVM)—not an "agent" in the sense of AI or autonomous software agents. This guest agent is a privileged, security-critical component whose sole purpose is to interface between the workload and the underlying TDX hardware, providing attestation and key management services. Unlike AI agents, which act autonomously or make decisions based on data, the guest agent in dstack is tightly scoped: it exposes authenticated RPC endpoints ([rpc_service.rs#L150](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150)) for cryptographic operations such as ECDSA key derivation, certificate signing, and TDX quote generation. + +The security model for the guest agent is fundamentally different from that of AI agents. The guest agent is designed to enforce strict isolation between application contexts, ensuring that no keys or attestation data can leak between tenants or workloads. For example, the `get_tls_key` method generates a random seed, derives a unique ECDSA key pair, and requests a signed certificate chain, while `get_quote` pads user data and requests a hardware-backed quote and event log. All requests are carefully validated, and the agent is engineered to prevent any cross-tenant key or attestation leakage. Its role is purely to mediate secure, hardware-rooted cryptographic operations on behalf of the guest environment, with a minimal and auditable attack surface. + +### KMS Integration + +The Key Management Service (KMS) uses TDX attestation to securely provision keys, following a chain-of-trust model where application keys are derived only from hardware-attested root keys. Before releasing any cryptographic material, the KMS rigorously verifies TDX quotes. + +#### How the Guest Agent Operates in the KMS Context + +Conceptually, the guest agent acts as the trusted bridge between the application running inside the CVM and the KMS, enabling secure, hardware-rooted key management. When an application within the CVM needs a cryptographic key, it communicates with the guest agent, which in turn generates a TDX quote that attests to the current state of the virtual machine. This quote, along with any required application-specific data, is sent to the KMS as part of a key request. + +The KMS, running outside the CVM (typically on the host or in a management domain), receives the attestation evidence from the guest agent. It verifies the TDX quote to ensure that the request is coming from a genuine, measured, and trusted environment. Only after successful verification does the KMS derive or release the requested key material, binding it to the attested state of the guest. This process ensures that keys are never provisioned to untrusted or tampered workloads. + +In summary, the guest agent is the only component inside the CVM with the privilege to interact directly with the TDX hardware and produce attestation evidence. Its role in the KMS workflow is to securely generate, package, and transmit this evidence, enabling the KMS to enforce strict hardware-based access control for all cryptographic operations. This design ensures that key provisioning is always rooted in verifiable hardware state, and that the attack surface for key compromise is minimized. + +> Integration security is where theory meets practice. The next section explores the threat model and security guarantees that underpin dStack's TDX attestation. + diff --git a/docs/security-research/tdx-att/tdx-overview.mdx b/docs/security-research/tdx-att/tdx-overview.mdx new file mode 100644 index 00000000..9f1a7642 --- /dev/null +++ b/docs/security-research/tdx-att/tdx-overview.mdx @@ -0,0 +1,38 @@ +--- +title: "TDX Attestation Overview" +description: "Comprehensive introduction to dStack's Intel TDX attestation implementation and its security guarantees." +--- + +# TDX Attestation Security Analysis + +## TDX Overview + +dStack's TDX attestation system delivers hardware-backed cryptographic proof of execution integrity using Intel Trust Domain Extensions (TDX). At its core, the implementation is powered by the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs), which directly interfaces with Intel TDX hardware to generate strong, unforgeable attestation quotes. + +TDX attestation is not just a technical feature—it's a paradigm shift in how trust is established in cloud and confidential computing. By anchoring the root of trust in hardware, dStack ensures that every layer of the software stack, from firmware to application, is measured, validated, and auditable. This approach provides a foundation for building secure, decentralized, and verifiable systems where users and organizations can confidently run sensitive workloads without fear of tampering or unauthorized access. + +## TDX Attestation Architectural Synthesis + +dStack's TDX attestation security architecture is designed as an end-to-end chain of verifiable trust, beginning at the Intel TDX hardware root and extending through every software and policy layer involved in confidential workload execution. Each step of the process—from the first code loaded by the TDX module, to the runtime configuration of guest VMs, and up to the application—contributes cryptographically measured evidence to an immutable trust chain. + +What makes this model robust is its compositional layering: every system stage (firmware, kernel, initrd, application) records its state in hardware-backed measurement registers, and these are captured and sealed in an attestation quote—cryptographically signed by Intel's hardware-rooted key infrastructure. Validation does not stop at signature checking: event log replay, measurement validation, and report data binding all ensure that not only was the environment authentic at a moment in time, but that its entire boot and runtime sequence is tamper-evident and externally auditable. + +By combining TDX's hardware assurances with policy enforcement through smart contracts and cryptographically controlled key management, dStack provides a closed loop of attestation, authorization, and key provisioning. This architecture makes it possible to deliver both continuous runtime integrity and decentralized, verifiable trust for confidential applications and distributed systems. + +## TDX Attestation Security + +tdx attestation is a process by which a confidential virtual machine (cvm) proves to a remote verifier that it is running on genuine intel tdx hardware and that its entire software stack—from firmware and kernel to application—has not been tampered with. this is achieved by measuring each stage of the boot and runtime process, sealing these measurements into a signed attestation quote, and providing cryptographic evidence that can be externally validated. + +while both tdx and intel sgx provide hardware-backed attestation, there are key differences between them. sgx attestation is focused on user-space enclaves, measuring and attesting only the code and data within a specific enclave. tdx attestation, on the other hand, operates at the virtual machine level, capturing the integrity of the entire guest os, kernel, and all applications. tdx introduces a set of runtime measurement registers (rtmrs) and a cryptographically secure event log, enabling full transparency and replay of the system's trust chain. tdx also supports more flexible report data binding and is designed for cloud-scale confidential computing, integrating with key management and policy systems to support complex, multi-tenant workloads. + +the following section describes the comprehensive, multi-layered trust and attestation flow in dstack's tdx security architecture. each component and connection is designed to ensure that every stage of the workload lifecycle—from hardware boot to application execution and key provisioning—is cryptographically measured, auditable, and verifiable. + +- **Hardware Root of Trust:** The process begins with Intel TDX hardware, establishing a silicon-anchored root of trust. The TDX Module (SEAM Mode) manages the secure launch and measurement of the firmware and subsequent layers. +- **Boot Chain Integrity:** The OVMF firmware, Linux kernel, initrd, and dStack application are each measured and extended into dedicated RTMRs (Runtime Measurement Registers), ensuring that any modification or tampering is detectable. +- **Measurement Registers:** MRTD and RTMR0–3 capture the state of hardware configuration, kernel, initrd, and application. These measurements are chained and sealed into the attestation quote. +- **Quote Generation & Event Logging:** The TDX Quote Generator collects all RTMR values and report data, producing a signed attestation quote. Simultaneously, a cryptographically secure event log records every measurement extension, supporting full replay and auditability. +- **Quote Verification & KMS Integration:** The quote, along with the event log, is verified against Intel's CA root keys. The KMS node then authenticates the attestation, interacts with smart contracts for policy enforcement, and manages root/app keys for secure provisioning. +- **Trust Verification & Policy Enforcement:** Additional verification steps—such as image verification, measurement recalculation, and signature chain validation—ensure that only trusted workloads receive cryptographic keys and access. + +> This overview sets the stage for a deep dive into each architectural and security component of dStack's TDX attestation. Continue reading the following sections for a comprehensive understanding of how each layer contributes to the overall security model. + diff --git a/docs/security-research/tdx-att/tdx-quote-gen.mdx b/docs/security-research/tdx-att/tdx-quote-gen.mdx new file mode 100644 index 00000000..1fdc67de --- /dev/null +++ b/docs/security-research/tdx-att/tdx-quote-gen.mdx @@ -0,0 +1,38 @@ +--- +title: "TDX Quote Generation and Verification" +description: "In-depth explanation of how TDX quotes are generated, bound, and verified in dStack." +--- + +## Quote Generation and Verification + +In Intel TDX, a "quote" is a cryptographically signed data structure that serves as the primary evidence for remote attestation. For both technical implementers and security researchers, it's important to understand that a TDX quote is generated by the TDX hardware itself, not by software running in the guest or host. This quote proves to a remote verifier that a specific virtual machine (Trusted Domain, or TD) is running on genuine TDX-capable silicon, and that its measured state—including firmware, kernel, and application—matches a set of expected, verifiable values. + +A TDX quote contains three main elements: +- **TD Report:** A summary of the current state of the system's measurement registers (RTMRs), which reflect the integrity of the firmware, kernel, and application stack. +- **Attestation Key Identifier:** A unique identifier for the hardware-provisioned attestation key used to sign the quote. +- **Digital Signature:** An ECDSA signature rooted in Intel's hardware-backed key infrastructure, ensuring the authenticity and integrity of the quote. + +This mechanism is foundational for confidential computing. It allows any external party—regardless of their privilege level or network position—to independently verify the integrity and authenticity of a workload, without having to trust the host OS, hypervisor, or cloud provider. In dstack, TDX quotes are the cornerstone of attestation and key management: every cryptographic operation and policy decision is anchored in hardware-verifiable state. + +Below, we detail how dstack generates, binds, and integrates TDX quotes into its security architecture: + +### Quote Structure and Content + +Each TDX quote produced by dstack includes: +- The raw TD report (capturing the current RTMR values and other state), +- The attestation key ID, +- An ECDSA signature. + +The guest agent is responsible for generating these quotes securely. It ensures that any user-supplied data is padded to exactly 64 bytes (the required size for TDX report data) and then invokes the TDX hardware attestation APIs. For implementation details, see [rpc_service.rs#L150](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150). + +### Report Data Binding + +The 64-byte report data field in the TDX quote allows applications to cryptographically bind arbitrary data to their attestation. This is a powerful feature for both security and flexibility: for example, you can bind a nonce, a public key, or an application identifier to the attestation, ensuring that the quote is unique to a specific context or session. + +dstack supports a wide range of cryptographic hash algorithms for this binding—including SHA-256, SHA-384, SHA-512, and Keccak—as described in [attestation.rs#L32](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L32). The implementation strictly enforces both the length and content of the report data, ensuring compliance with TDX's data-binding requirements and preventing misuse. + +### Certificate Integration + +dstack's RA-TLS (Remote Attestation TLS) system integrates TDX quotes directly into X.509 certificates as custom extensions. This means that remote attestation is performed as part of the standard TLS handshake, with no need for out-of-band verification steps. When a client or server presents its certificate, the verifier can extract and validate the embedded TDX quote using the [`from_cert`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L260) method. This approach provides a seamless, cryptographically linked trust chain—from the hardware root of trust, through the attestation evidence, all the way to the TLS endpoint—enabling both strong security guarantees and operational simplicity for confidential workloads. + +> The process of quote generation and verification is the linchpin of dStack's attestation model. The next section delves into the verification security model, where these quotes are rigorously validated and enforced. diff --git a/docs/security-research/tdx-att/tdx-security-arch.mdx b/docs/security-research/tdx-att/tdx-security-arch.mdx new file mode 100644 index 00000000..e7d4f9a8 --- /dev/null +++ b/docs/security-research/tdx-att/tdx-security-arch.mdx @@ -0,0 +1,38 @@ +--- +title: "TDX Security Architecture" +description: "Detailed breakdown of the security architecture underpinning dStack's TDX attestation." +--- + +## Security Architecture + +Establishing hardware-rooted security at scale presents significant challenges. It is not sufficient to simply deploy specialized hardware such as Intel TDX; a comprehensive framework is also required to ensure that trust can be established, measured, and remotely verified by any party, regardless of their location or privilege level. Intel TDX provides the foundational capability for remote attestation by enabling the creation of isolated Trusted Domains (TDs), each capable of generating cryptographically signed evidence of its current state. However, even with these capabilities, TDs remain potentially vulnerable to a variety of attack vectors, including those originating from privileged system software or compromised infrastructure. + +The core security challenge is to guarantee that only genuine, uncompromised environments are able to prove their integrity. This is essential for scenarios where highly confidential data or workloads must be shared or processed under strict confidentiality agreements, allowing authorized parties to interact with sensitive resources without risk of tampering or data leakage. + +To address these challenges, the dStack framework is architected around the principles of remote trusted domains. It leverages the full suite of TDX’s standards for measurement, event logging, and attestation, and augments them with advanced mechanisms such as cryptographic key management, policy enforcement, and continuous verification. The following subsections detail the architectural decisions and mechanisms that underpin this approach, providing a clear conceptual foundation for understanding how dStack delivers secure, auditable, and scalable confidential computing on top of Intel TDX. + +### Hardware Root of Trust + +The attestation system in dStack is fundamentally anchored in Intel TDX CPU instructions, which are designed to produce TD reports that are cryptographically resistant to forgery—even in the presence of malicious hypervisors or privileged host software. All critical low-level operations interact directly with the CPU using instructions such as [`tdx_att_get_report`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L88) and [`tdx_att_get_quote`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L52). This direct invocation ensures that the root of trust is established in hardware (silicon), minimizing the attack surface and eliminating reliance on potentially compromised software layers. + +### Cryptographic Foundations + +Each attestation quote generated by the system is protected by an ECDSA signature, using attestation keys provisioned directly by Intel. This cryptographic process, as implemented in the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs), guarantees that only authentic TDX hardware can produce valid attestation quotes. Every quote encapsulates a 1024-byte TDX report, which includes the current values of all measurement registers and a 64-byte report data field. This report data field enables cryptographic binding of application-specific data to the attestation, supporting advanced use cases such as secure key provisioning and policy enforcement. + +### Runtime Measurement Registers (RTMRs) + +The TDX security architecture is structured around four Runtime Measurement Registers (RTMRs), each of which defines a distinct trust boundary within the system: + +- **RTMR0:** Captures the virtual hardware configuration, such as CPU count and memory size. +- **RTMR1:** Records the measurement of the Linux kernel. +- **RTMR2:** Contains measurements of the kernel command line and the initramfs. +- **RTMR3:** Tracks application runtime measurements, including compose hashes, instance IDs, and other application-specific data. + +Each RTMR is extended and updated using SHA-384 hashing, which provides strong cryptographic guarantees for state tracking and tamper evidence. This mechanism creates a verifiable, append-only log of all measurement events, as detailed in [linux.rs#L129](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L129) and further explained in the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs). By chaining measurements in this way, the system ensures that any modification to the boot or runtime environment is immediately detectable and can be independently audited by external verifiers. + +### Event Log Security + +dStack’s attestation system maintains a cryptographically secure event log, recording every RTMR extension ([linux.rs#L105](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L105)). Each event contains the measurement register index, event type, descriptive metadata, and payload. The replay logic ([attestation.rs#L421](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L421)) enables auditors to verify that RTMR values are consistent with all prior measurements, providing full transparency for the system’s integrity chain. + +> The security architecture is the backbone of dStack’s TDX attestation, ensuring that every component and event is measured, logged, and verifiable. The next section explores how these architectural elements are leveraged in the quote generation and verification process. + diff --git a/docs/security-research/tdx-att/tdx-threat-model-garentees.mdx b/docs/security-research/tdx-att/tdx-threat-model-garentees.mdx new file mode 100644 index 00000000..00408e92 --- /dev/null +++ b/docs/security-research/tdx-att/tdx-threat-model-garentees.mdx @@ -0,0 +1,24 @@ +--- +title: "TDX Threat Model and Security Guarantees" +description: "A detailed look at the threat model, what dStack's TDX attestation protects against, and the guarantees it provides." +--- + +## Threat Model and Security Guarantees + +### What the System Protects Against + +dStack's attestation system, as described in the [dstack attestation design doc](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md), is built to defend against powerful adversaries, including malicious hypervisors and privileged hosts. Hardware-enforced measurements, RTMR monitoring, and strict TCB validation ensure that runtime or rollback attacks are detected. Nonce-based binding in attestation exchanges counters man-in-the-middle attacks by guaranteeing freshness and cryptographic linkage between verifier challenges and enclave attestations. + +The threat model for dStack's TDX attestation is comprehensive, considering not only external attackers but also those with privileged access to the host or hypervisor. By leveraging hardware-backed measurements and cryptographic validation, dStack ensures that even sophisticated adversaries cannot subvert the integrity of confidential workloads. + +### Verification Requirements + +End-to-end security requires verifying the dStack source code, building enclave images from source, and calculating expected measurement values as explained in [attestation.md §2.2: determining expected MRs](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#22-determining-expected-mrs). Once calculated, these measurements must match the values in the quote, and the event log must be replayed to confirm the accuracy of RTMR3 and the entire trust chain. + +This rigorous approach ensures that only trusted, reproducible environments are attested and that any deviation from the expected state is immediately detectable. The replay of the event log is a critical step, providing auditors with a transparent and tamper-evident record of every measurement and extension. + +### Trust Boundaries + +dStack clearly defines all trust boundaries, starting with Intel TDX hardware as the immutable root of trust. Measurements flow through each stage—virtual firmware, Linux kernel, initramfs, and user applications—and each layer is independently validated. For more detail on how TDX quote measurements correspond to these boundaries, see [attestation.md §2.1: understanding tdx quote measurements](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#21-understanding-tdx-quote-measurements). + +> The threat model and security guarantees provide the foundation for dStack's cryptographic implementation. The next section explores the technical details of how these guarantees are realized in code and protocol. diff --git a/docs/security-research/tdx-att/tdx-verification-model.mdx b/docs/security-research/tdx-att/tdx-verification-model.mdx new file mode 100644 index 00000000..ea205148 --- /dev/null +++ b/docs/security-research/tdx-att/tdx-verification-model.mdx @@ -0,0 +1,24 @@ +--- +title: "TDX Verification Security Model" +description: "Comprehensive explanation of the verification process and security model for TDX attestation in dStack." +--- + +## Verification Security Model + +Verification is a critical component of confidential computing, as it provides independent assurance that a workload is running on genuine TDX hardware and that its measured state matches expected, trusted values. In practice, this means verifying not only the cryptographic integrity of the attestation evidence, but also the Trusted Computing Base (TCB)—the combination of hardware, firmware, and software components that must remain secure for the system to be trustworthy. TCB validation ensures that only production, non-debug environments are attested, and that all critical measurements (such as firmware, kernel, and application hashes) are as expected. + +### Quote Verification Process + +Quotes are verified with the [`verify_with_ra_pubkey`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L291) function, which checks the ECDSA signature in the TDX quote against Intel's public key infrastructure and the RA-TLS public key. It also performs TCB (Trusted Computing Base) checks, and replays the event log to confirm RTMR values reflect the real sequence of system measurements. This robust process ensures attestation is both cryptographically bound to the TLS certificate and accurately describes the enclave's state. + +Traditionally, TDX quote verification is performed by a remote verifier or attestation service, which must be trusted to validate the quote and enforce policy. However, dStack introduces a novel enhancement: TDX attestation verification can now also be performed on-chain, directly on the blockchain. This means that the integrity and authenticity of TDX quotes can be validated in a decentralized, transparent, and tamper-evident manner, without relying solely on off-chain verifiers. By anchoring attestation results on the blockchain, dStack enables new models of trust and auditability, allowing any participant to independently verify the security posture of workloads in real time. + +### TCB Validation + +Strict TCB validation is enforced, with the system rejecting debug-enabled TDs and confirming that key measurement registers (`mr_signer_seam`, `mr_service_td`, etc.) match expected values. This is handled in the [`validate_tcb`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L346) function, which inspects the TD report for debug attributes and validates critical fields. For SGX enclaves, it also ensures debug attributes are not set. This protects production deployments by refusing to attest development or potentially compromised environments. + +### Measurement Chain Validation + +dStack reconstructs and verifies the entire measurement chain, from the Measurement Root of Trust for Data (MRTD) through all RTMRs and application identifiers. The [`decode_app_info`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L156) function replays the event log and extracts key fields from the TDX report, computing digests like `mr_system` (hashing `mr_td`, RTMR0-2, and the key provider measurement) and `mr_aggregated` (covering all RTMRs and additional fields). This process ensures every element of the trust chain—from firmware and kernel to application identity—is independently validated. + +> The verification security model is essential for maintaining trust in confidential computing. The next section explores how dStack integrates these guarantees into real-world deployments and operational workflows. diff --git a/docs/security-research/tdx-attestation.mdx b/docs/security-research/tdx-attestation.mdx new file mode 100644 index 00000000..ea29e3c3 --- /dev/null +++ b/docs/security-research/tdx-attestation.mdx @@ -0,0 +1,206 @@ +--- +title: "TDX Attestation Security" +description: "Deep dive into dstack's Intel TDX attestation implementation and security guarantees" +--- + +# TDX Attestation Security Analysis + +## TDXOverview + +dStack’s TDX attestation system delivers hardware-backed cryptographic proof of execution integrity using Intel Trust Domain Extensions (TDX). At its core, the implementation is powered by the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs), which directly interfaces with Intel TDX hardware to generate strong, unforgeable attestation quotes. + +## TDX Attestation Architectural Synthesis + +dStack’s TDX attestation security architecture is designed as an end-to-end chain of verifiable trust, beginning at the Intel TDX hardware root and extending through every software and policy layer involved in confidential workload execution. Each step of the process—from the first code loaded by the TDX module, to the runtime configuration of guest VMs, and up to the application—contributes cryptographically measured evidence to an immutable trust chain. + +What makes this model robust is its compositional layering: every system stage (firmware, kernel, initrd, application) records its state in hardware-backed measurement registers, and these are captured and sealed in an attestation quote—cryptographically signed by Intel’s hardware-rooted key infrastructure. Validation does not stop at signature checking: event log replay, measurement validation, and report data binding all ensure that not only was the environment authentic at a moment in time, but that its entire boot and runtime sequence is tamper-evident and externally auditable. + +By combining TDX’s hardware assurances with policy enforcement through smart contracts and cryptographically controlled key management, dStack provides a closed loop of attestation, authorization, and key provisioning. This architecture makes it possible to deliver both continuous runtime integrity and decentralized, verifiable trust for confidential applications and distributed systems. + +## TDX Attestation Security + +tdx attestation is a process by which a confidential virtual machine (cvm) proves to a remote verifier that it is running on genuine intel tdx hardware and that its entire software stack—from firmware and kernel to application—has not been tampered with. this is achieved by measuring each stage of the boot and runtime process, sealing these measurements into a signed attestation quote, and providing cryptographic evidence that can be externally validated. + +while both tdx and intel sgx provide hardware-backed attestation, there are key differences between them. sgx attestation is focused on user-space enclaves, measuring and attesting only the code and data within a specific enclave. tdx attestation, on the other hand, operates at the virtual machine level, capturing the integrity of the entire guest os, kernel, and all applications. tdx introduces a set of runtime measurement registers (rtmrs) and a cryptographically secure event log, enabling full transparency and replay of the system’s trust chain. tdx also supports more flexible report data binding and is designed for cloud-scale confidential computing, integrating with key management and policy systems to support complex, multi-tenant workloads. + +the following section describes the comprehensive, multi-layered trust and attestation flow in dstack’s tdx security architecture. each component and connection is designed to ensure that every stage of the workload lifecycle—from hardware boot to application execution and key provisioning—is cryptographically measured, auditable, and verifiable. + +- **Hardware Root of Trust:** The process begins with Intel TDX hardware, establishing a silicon-anchored root of trust. The TDX Module (SEAM Mode) manages the secure launch and measurement of the firmware and subsequent layers. +- **Boot Chain Integrity:** The OVMF firmware, Linux kernel, initrd, and dStack application are each measured and extended into dedicated RTMRs (Runtime Measurement Registers), ensuring that any modification or tampering is detectable. +- **Measurement Registers:** MRTD and RTMR0–3 capture the state of hardware configuration, kernel, initrd, and application. These measurements are chained and sealed into the attestation quote. +- **Quote Generation & Event Logging:** The TDX Quote Generator collects all RTMR values and report data, producing a signed attestation quote. Simultaneously, a cryptographically secure event log records every measurement extension, supporting full replay and auditability. +- **Quote Verification & KMS Integration:** The quote, along with the event log, is verified against Intel’s CA root keys. The KMS node then authenticates the attestation, interacts with smart contracts for policy enforcement, and manages root/app keys for secure provisioning. +- **Trust Verification & Policy Enforcement:** Additional verification steps—such as image verification, measurement recalculation, and signature chain validation—ensure that only trusted workloads receive cryptographic keys and access. + + +--- + + +## Security Architecture + +Establishing hardware-rooted security at scale presents significant challenges. It is not sufficient to simply deploy specialized hardware such as Intel TDX; a comprehensive framework is also required to ensure that trust can be established, measured, and remotely verified by any party, regardless of their location or privilege level. Intel TDX provides the foundational capability for remote attestation by enabling the creation of isolated Trusted Domains (TDs), each capable of generating cryptographically signed evidence of its current state. However, even with these capabilities, TDs remain potentially vulnerable to a variety of attack vectors, including those originating from privileged system software or compromised infrastructure. + +The core security challenge is to guarantee that only genuine, uncompromised environments are able to prove their integrity. This is essential for scenarios where highly confidential data or workloads must be shared or processed under strict confidentiality agreements, allowing authorized parties to interact with sensitive resources without risk of tampering or data leakage. + +To address these challenges, the dStack framework is architected around the principles of remote trusted domains. It leverages the full suite of TDX’s standards for measurement, event logging, and attestation, and augments them with advanced mechanisms such as cryptographic key management, policy enforcement, and continuous verification. The following subsections detail the architectural decisions and mechanisms that underpin this approach, providing a clear conceptual foundation for understanding how dStack delivers secure, auditable, and scalable confidential computing on top of Intel TDX. + +### Hardware Root of Trust + +The attestation system in dStack is fundamentally anchored in Intel TDX CPU instructions, which are designed to produce TD reports that are cryptographically resistant to forgery—even in the presence of malicious hypervisors or privileged host software. All critical low-level operations interact directly with the CPU using instructions such as [`tdx_att_get_report`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L88) and [`tdx_att_get_quote`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L52). This direct invocation ensures that the root of trust is established in hardware (silicon), minimizing the attack surface and eliminating reliance on potentially compromised software layers. + +### Cryptographic Foundations + +Each attestation quote generated by the system is protected by an ECDSA signature, using attestation keys provisioned directly by Intel. This cryptographic process, as implemented in the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs), guarantees that only authentic TDX hardware can produce valid attestation quotes. Every quote encapsulates a 1024-byte TDX report, which includes the current values of all measurement registers and a 64-byte report data field. This report data field enables cryptographic binding of application-specific data to the attestation, supporting advanced use cases such as secure key provisioning and policy enforcement. + +### Runtime Measurement Registers (RTMRs) + +The TDX security architecture is structured around four Runtime Measurement Registers (RTMRs), each of which defines a distinct trust boundary within the system: + +- **RTMR0:** Captures the virtual hardware configuration, such as CPU count and memory size. +- **RTMR1:** Records the measurement of the Linux kernel. +- **RTMR2:** Contains measurements of the kernel command line and the initramfs. +- **RTMR3:** Tracks application runtime measurements, including compose hashes, instance IDs, and other application-specific data. + +Each RTMR is extended and updated using SHA-384 hashing, which provides strong cryptographic guarantees for state tracking and tamper evidence. This mechanism creates a verifiable, append-only log of all measurement events, as detailed in [linux.rs#L129](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L129) and further explained in the [`tdx-attest` crate](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/tdx-attest/src/lib.rs). By chaining measurements in this way, the system ensures that any modification to the boot or runtime environment is immediately detectable and can be independently audited by external verifiers. + +### Event Log Security + +dStack’s attestation system maintains a cryptographically secure event log, recording every RTMR extension ([linux.rs#L105](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L105)). Each event contains the measurement register index, event type, descriptive metadata, and payload. The replay logic ([attestation.rs#L421](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L421)) enables auditors to verify that RTMR values are consistent with all prior measurements, providing full transparency for the system’s integrity chain. + + +--- + + +## Quote Generation and Verification + +In Intel TDX, a "quote" is a cryptographically signed data structure that serves as the primary evidence for remote attestation. For both technical implementers and security researchers, it's important to understand that a TDX quote is generated by the TDX hardware itself, not by software running in the guest or host. This quote proves to a remote verifier that a specific virtual machine (Trusted Domain, or TD) is running on genuine TDX-capable silicon, and that its measured state—including firmware, kernel, and application—matches a set of expected, verifiable values. + +A TDX quote contains three main elements: +- **TD Report:** A summary of the current state of the system’s measurement registers (RTMRs), which reflect the integrity of the firmware, kernel, and application stack. +- **Attestation Key Identifier:** A unique identifier for the hardware-provisioned attestation key used to sign the quote. +- **Digital Signature:** An ECDSA signature rooted in Intel’s hardware-backed key infrastructure, ensuring the authenticity and integrity of the quote. + +This mechanism is foundational for confidential computing. It allows any external party—regardless of their privilege level or network position—to independently verify the integrity and authenticity of a workload, without having to trust the host OS, hypervisor, or cloud provider. In dstack, TDX quotes are the cornerstone of attestation and key management: every cryptographic operation and policy decision is anchored in hardware-verifiable state. + +Below, we detail how dstack generates, binds, and integrates TDX quotes into its security architecture: + +### Quote Structure and Content + +Each TDX quote produced by dstack includes: +- The raw TD report (capturing the current RTMR values and other state), +- The attestation key ID, +- An ECDSA signature. + +The guest agent is responsible for generating these quotes securely. It ensures that any user-supplied data is padded to exactly 64 bytes (the required size for TDX report data) and then invokes the TDX hardware attestation APIs. For implementation details, see [rpc_service.rs#L150](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150). + +### Report Data Binding + +The 64-byte report data field in the TDX quote allows applications to cryptographically bind arbitrary data to their attestation. This is a powerful feature for both security and flexibility: for example, you can bind a nonce, a public key, or an application identifier to the attestation, ensuring that the quote is unique to a specific context or session. + +dstack supports a wide range of cryptographic hash algorithms for this binding—including SHA-256, SHA-384, SHA-512, and Keccak—as described in [attestation.rs#L32](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L32). The implementation strictly enforces both the length and content of the report data, ensuring compliance with TDX’s data-binding requirements and preventing misuse. + + + + +### Certificate Integration + +dstack’s RA-TLS (Remote Attestation TLS) system integrates TDX quotes directly into X.509 certificates as custom extensions. This means that remote attestation is performed as part of the standard TLS handshake, with no need for out-of-band verification steps. When a client or server presents its certificate, the verifier can extract and validate the embedded TDX quote using the [`from_cert`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L260) method. This approach provides a seamless, cryptographically linked trust chain—from the hardware root of trust, through the attestation evidence, all the way to the TLS endpoint—enabling both strong security guarantees and operational simplicity for confidential workloads. + +--- + +## Verification Security Model + +Verification is a critical component of confidential computing, as it provides independent assurance that a workload is running on genuine TDX hardware and that its measured state matches expected, trusted values. In practice, this means verifying not only the cryptographic integrity of the attestation evidence, but also the Trusted Computing Base (TCB)—the combination of hardware, firmware, and software components that must remain secure for the system to be trustworthy. TCB validation ensures that only production, non-debug environments are attested, and that all critical measurements (such as firmware, kernel, and application hashes) are as expected. + +### Quote Verification Process + +Quotes are verified with the [`verify_with_ra_pubkey`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L291) function, which checks the ECDSA signature in the TDX quote against Intel’s public key infrastructure and the RA-TLS public key. It also performs TCB (Trusted Computing Base) checks, and replays the event log to confirm RTMR values reflect the real sequence of system measurements. This robust process ensures attestation is both cryptographically bound to the TLS certificate and accurately describes the enclave’s state. + +Traditionally, TDX quote verification is performed by a remote verifier or attestation service, which must be trusted to validate the quote and enforce policy. However, dStack introduces a novel enhancement: TDX attestation verification can now also be performed on-chain, directly on the blockchain. This means that the integrity and authenticity of TDX quotes can be validated in a decentralized, transparent, and tamper-evident manner, without relying solely on off-chain verifiers. By anchoring attestation results on the blockchain, dStack enables new models of trust and auditability, allowing any participant to independently verify the security posture of workloads in real time. + +### TCB Validation + +Strict TCB validation is enforced, with the system rejecting debug-enabled TDs and confirming that key measurement registers (`mr_signer_seam`, `mr_service_td`, etc.) match expected values. This is handled in the [`validate_tcb`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L346) function, which inspects the TD report for debug attributes and validates critical fields. For SGX enclaves, it also ensures debug attributes are not set. This protects production deployments by refusing to attest development or potentially compromised environments. + +### Measurement Chain Validation + +dStack reconstructs and verifies the entire measurement chain, from the Measurement Root of Trust for Data (MRTD) through all RTMRs and application identifiers. The [`decode_app_info`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L156) function replays the event log and extracts key fields from the TDX report, computing digests like `mr_system` (hashing `mr_td`, RTMR0-2, and the key provider measurement) and `mr_aggregated` (covering all RTMRs and additional fields). This process ensures every element of the trust chain—from firmware and kernel to application identity—is independently validated. + +--- + + +## Integration Security + +How the Guest Agent Operates + + +### Guest Agent Security + +When we refer to a "guest agent" in the context of dstack and TDX attestation, we mean a dedicated system process running inside the confidential virtual machine (CVM)—not an "agent" in the sense of AI or autonomous software agents. This guest agent is a privileged, security-critical component whose sole purpose is to interface between the workload and the underlying TDX hardware, providing attestation and key management services. Unlike AI agents, which act autonomously or make decisions based on data, the guest agent in dstack is tightly scoped: it exposes authenticated RPC endpoints ([rpc_service.rs#L150](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150)) for cryptographic operations such as ECDSA key derivation, certificate signing, and TDX quote generation. + +The security model for the guest agent is fundamentally different from that of AI agents. The guest agent is designed to enforce strict isolation between application contexts, ensuring that no keys or attestation data can leak between tenants or workloads. For example, the `get_tls_key` method generates a random seed, derives a unique ECDSA key pair, and requests a signed certificate chain, while `get_quote` pads user data and requests a hardware-backed quote and event log. All requests are carefully validated, and the agent is engineered to prevent any cross-tenant key or attestation leakage. Its role is purely to mediate secure, hardware-rooted cryptographic operations on behalf of the guest environment, with a minimal and auditable attack surface. + +### KMS Integration + +The Key Management Service (KMS) uses TDX attestation to securely provision keys, following a chain-of-trust model where application keys are derived only from hardware-attested root keys. Before releasing any cryptographic material, the KMS rigorously verifies TDX quotes. + +#### How the Guest Agent Operates in the KMS Context + +Conceptually, the guest agent acts as the trusted bridge between the application running inside the CVM and the KMS, enabling secure, hardware-rooted key management. When an application within the CVM needs a cryptographic key, it communicates with the guest agent, which in turn generates a TDX quote that attests to the current state of the virtual machine. This quote, along with any required application-specific data, is sent to the KMS as part of a key request. + +The KMS, running outside the CVM (typically on the host or in a management domain), receives the attestation evidence from the guest agent. It verifies the TDX quote to ensure that the request is coming from a genuine, measured, and trusted environment. Only after successful verification does the KMS derive or release the requested key material, binding it to the attested state of the guest. This process ensures that keys are never provisioned to untrusted or tampered workloads. + +In summary, the guest agent is the only component inside the CVM with the privilege to interact directly with the TDX hardware and produce attestation evidence. Its role in the KMS workflow is to securely generate, package, and transmit this evidence, enabling the KMS to enforce strict hardware-based access control for all cryptographic operations. This design ensures that key provisioning is always rooted in verifiable hardware state, and that the attack surface for key compromise is minimized. + + +--- +## Threat Model and Security Guarantees + +### What the System Protects Against + +dStack’s attestation system, as described in the [dstack attestation design doc](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md), is built to defend against powerful adversaries, including malicious hypervisors and privileged hosts. Hardware-enforced measurements, RTMR monitoring, and strict TCB validation ensure that runtime or rollback attacks are detected. Nonce-based binding in attestation exchanges counters man-in-the-middle attacks by guaranteeing freshness and cryptographic linkage between verifier challenges and enclave attestations. + +### Verification Requirements + +End-to-end security requires verifying the dStack source code, building enclave images from source, and calculating expected measurement values as explained in [attestation.md §2.2: determining expected MRs](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#22-determining-expected-mrs). Once calculated, these measurements must match the values in the quote, and the event log must be replayed to confirm the accuracy of RTMR3 and the entire trust chain. + +### Trust Boundaries + +dStack clearly defines all trust boundaries, starting with Intel TDX hardware as the immutable root of trust. Measurements flow through each stage—virtual firmware, Linux kernel, initramfs, and user applications—and each layer is independently validated. For more detail on how TDX quote measurements correspond to these boundaries, see [attestation.md §2.1: understanding tdx quote measurements](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#21-understanding-tdx-quote-measurements). + +## Cryptographic Implementation Details + +### Hash Algorithm Support + +The attestation layer supports a full range of cryptographic hash algorithms for report data binding, as implemented in [`attestation.rs#L33`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L33). By default, `sha512` is used, but options include `sha256`, `sha384`, all SHA-3 variants, Keccak, and a `raw` mode for direct data binding. Every report data input is prefixed with a content tag (e.g., `kms-root-ca`, `ratls-cert`, `app-data`), ensuring context-specific and unambiguous measurements. This allows applications to select the most suitable hash algorithm, while maintaining interoperability and high security. + +### Key Derivation Security + +All application keys are deterministically derived from hardware-sealed root keys, using application-specific identifiers for cryptographic isolation between tenants. The guest agent’s [`get_key`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L150C1-L239C2) RPC method implements this: a root ECDSA key derives per-application keys by path, then signs the derived public key and usage context. This signature chain allows independent verification that every derived key is both valid and bound to the right application, so that only trusted code can use it. + +## Error Handling and Security + +The TDX attestation implementation features robust, granular error handling with a dedicated `TdxAttestError` enum ([source](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L20C1-L50C2)). Every failure mode—unexpected errors, invalid parameters, resource exhaustion, hardware failures, and more—has a unique error code and message. This enables both secure operation and straightforward debugging, as each error can be quickly identified and acted upon. + +## Simulator Mode Security + +For development and testing, dStack provides a simulator mode that emulates the production attestation API using pre-generated quotes and event logs. The simulation logic is in [`simulate_quote`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/guest-agent/src/rpc_service.rs#L241), which loads simulated artifacts and substitutes the report data field with caller input. Simulator mode is strictly disabled in production builds, ensuring only genuine, hardware-backed attestation is accepted in secure environments. + +## Security Monitoring and Auditability + +Every runtime measurement is persistently logged, with each event cryptographically bound to its RTMR extension ([`log_rtmr_event`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/tdx-attest/src/linux.rs#L105)). Events are serialized as JSON and stored in a secure log directory, allowing full post-hoc verification. Auditors can replay and validate the entire execution history, verifying every measurement and trust boundary that dStack enforces. + +## Notes + +dStack’s TDX attestation provides enterprise-grade security through hardware-rooted trust, complete measurement chains, and rigorous verification at every level. The platform’s guarantees rest on Intel TDX hardware, robust cryptographic construction, and careful, modular validation of all trust boundaries. This design enables flexible deployment for a range of use cases—while ensuring uncompromising security properties wherever it’s used. + +## References + +- [Intel TDX Module 1.5 Specification](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-trust-domain-extensions.html) +- [dstack Attestation Design Doc](https://github.com/Dstack-TEE/dstack/blob/master/attestation.md) + +
+

+ Next Component: Learn how attestation integrates with the VMM security architecture. +

+
diff --git a/docs/security-research/vmm-security.mdx b/docs/security-research/vmm-security.mdx new file mode 100644 index 00000000..ea3ac11a --- /dev/null +++ b/docs/security-research/vmm-security.mdx @@ -0,0 +1,248 @@ +--- +title: "VMM Security Architecture" +description: "In-depth analysis of dstack VMM's security boundaries and isolation mechanisms" +--- + +# VMM Security Architecture + +`dstack-vmm` ([source](https://github.com/Dstack-TEE/dstack/tree/master/vmm)) + +The Virtual Machine Monitor (VMM) within the Dstack ecosystem, known specifically as dstack-vmm, serves as the central orchestrator managing the lifecycle and operations of Confidential Virtual Machines (CVMs) running in secure execution environments enabled by Intel Trust Domain Extensions (TDX). Acting as an advanced hypervisor management layer, dstack-vmm abstracts and simplifies the deployment of containerized applications within hardware-enforced trusted boundaries, providing unified mechanisms for VM provisioning, resource allocation, and operational control. It seamlessly integrates key security services, including cryptographic measurement and attestation workflows, through interaction with the Key Management Service (dstack-kms), and ensures secure connectivity via the gateway component (dstack-gateway). With clearly defined interfaces spanning RPC, web-based consoles, and CLI, the VMM enables robust, automated, and flexible management suited for confidential computing environments. Built upon foundational trust in Intel TDX hardware, dstack-vmm’s architecture leverages sophisticated measurement and attestation models, establishing secure execution contexts even amidst potentially compromised host systems, thus combining comprehensive security assurances with practical usability. + +## Overview + +The `dstack-vmm` serves as the primary security boundary between untrusted host infrastructure and confidential workloads. Its implementation is located in [`vmm/src/main.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/main.rs). Built upon QEMU/KVM with Intel TDX extensions, the VMM enforces hardware-backed memory isolation, manages the secure lifecycle of confidential VMs, generates attestation measurements, and mediates resource access—all within a Rust-based architecture designed for robust security guarantees. + +dstack-vmm architecture diagram + +--- + +## Security Model + +### Trust Boundaries + +*The security model for dstack-vmm is built around strict trust boundaries that separate the untrusted host environment from the confidential workloads running inside secure virtual machines. This model ensures that only the components within the trusted domain—protected by hardware-based isolation—can access sensitive data and operations, while the host and hardware outside this boundary are treated as untrusted. The following diagram illustrates these boundaries and the protections in place:* + +```mermaid +graph TB + subgraph "Untrusted Domain" + H["Host OS"] + HW["Hardware"] + end + + subgraph "Trusted Domain" + VMM["dstack-vmm"] + CVM["Confidential VM"] + APP["Application"] + end + + HW -->|"TDX Protection"| VMM + VMM -->|"Isolation"| CVM + CVM -->|"Secure Boot"| APP + H -.->|"No Access"| CVM +``` + + +### Intel TDX Hardware Security Properties + +The VMM leverages Intel TDX (Trust Domain Extensions) to provide hardware-enforced confidential computing. TDX automatically applies AES-256 memory encryption to all guest memory pages and ensures cryptographic integrity, preventing unauthorized modification ([Intel TDX Whitepaper §3.2](https://www.intel.com/content/dam/develop/external/us/en/documents/tdx-whitepaper-final9-17.pdf?utm_source=chatgpt.com)). + +Beyond memory encryption, TDX enforces CPU-state isolation by capturing the full register context inside Secure Arbitration Mode (SEAM) and preventing any host-initiated register inspection or tampering during VM exits and entries ([Linux Kernel TDX Documentation](https://www.kernel.org/doc/html/next/x86/tdx.html?utm_source=chatgpt.com)). Address-Translation Integrity protects the guest’s page tables against injection or replay attacks by verifying each update through the Runtime TDX Measurement Registers (RTMRs), which accumulate progressive hashes of firmware, bootloader, kernel, and critical components into a measured-boot chain of trust ([Intel Trust Authority – TD Integrity](https://docs.trustauthority.intel.com/main/articles/concept-td-integrity.html?utm_source=chatgpt.com)). + +To instantiate a TDX-protected CVM in QEMU, the VMM configures the VM to use the `q35` machine type—a modern Intel ICH9-style chipset emulation that supports PCI-Express, LPC, and all device models required for confidential computing. Legacy platforms like `i440fx` or `microvm` lack the necessary PCIe infrastructure and cannot host TDX guests ([Intel TDX Whitepaper §2.3](https://cdrdv2-public.intel.com/690419/TDX-Whitepaper-February2022.pdf?utm_source=chatgpt.com); [Wikipedia: Trust Domain Extensions](https://en.wikipedia.org/wiki/Trust_Domain_Extensions?utm_source=chatgpt.com)). + +In Dstack’s QEMU wrapper (see [`vmm/src/app/qemu.rs` at commit 45ebd05…#L320](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L320)), the invocation appears as: + +```rust +command + .arg("-machine") + .arg("q35,kernel-irqchip=split,confidential-guest-support=tdx,hpet=off"); + +let tdx_object = if cfg.use_mrconfigid { + // Compute mrconfigid for attestation binding... + format!("tdx-guest,id=tdx,mrconfigid={mrconfigid}") +} else { + "tdx-guest,id=tdx".to_string() +}; +command.arg("-object").arg(tdx_object); +``` + +* **`confidential-guest-support=tdx`** engages the TDX firmware interface. +* **`kernel-irqchip=split`** offloads interrupt emulation to the kernel’s KVM module for precise delivery under SEAM protection. +* **`hpet=off`** disables legacy timers that can conflict with TDX’s secure interrupt handling. +* **`-object tdx-guest,id=tdx[,mrconfigid=…]`** initializes the Intel TDX guest context and, if supplied, binds the computed MRCONFIGID for attestation. + +Finally, the VMM integrates with **dstack-kms** to automate remote attestation: it retrieves Intel TDX quotes—cryptographically signed bundles that bind the RTMR measurement chain to a public key—allowing external verifiers to validate the CVM’s boot sequence and runtime integrity before provisioning secrets. By combining AES-XTS memory encryption, SHA-3 MAC integrity, CPU-state isolation, address-translation integrity, and end-to-end attestation, Intel TDX provides a robust hardware-rooted security foundation that the Dstack VMM orchestrates for confidential computing environments. + + +## TDX Measurement and Attestation Framework + +To ensure that confidential workloads are only executed in a secure and trusted environment, Dstack VMM relies on a robust measurement and attestation process built on Intel TDX. This framework combines a tamper-evident measurement chain with flexible, policy-driven key management. The result: your confidential workloads are launched only on verified hardware and receive cryptographic materials strictly according to policy—never anywhere else. + +Before any confidential VM is allowed to run, Dstack VMM must demonstrate that both its hardware and software stack match expected, untampered states. This is achieved through Intel TDX’s Runtime Measurement Registers (RTMRs), which establish a “chain of trust” by cryptographically hashing each stage of the VM’s boot and runtime process: + +### 1. Building the Measurement Chain +- **MRTD (Measurement Register for Trust Domain)** + The first anchor in our chain: it records a digest of the TDX firmware (TDVF) itself, ensuring we started from the correct trusted foundation [1](#1-0). +- **RTMR0 (Firmware & Launch Environment)** + Captures post-boot firmware bytes and microcode patches, guaranteeing that no rogue microcode or modified SEAM loader was injected [2](#1-1). +- **RTMR1 (Bootloader & Kernel)** + Records the bootloader image and Linux kernel measurement, preventing kernel-level rootkits or patched initrd from slipping through [3](#1-2). +- **RTMR2 (Initial Userspace & Drivers)** + Hashes early userspace components (e.g., initramfs, critical drivers) so that only audited, integrity-checked drivers can execute [4](#1-3). +- **RTMR3 (Application Manifests & Runtime Libraries)** + Extends the chain into higher-level artifacts—application manifests, container images, and dynamic libraries—locking down the exact code you intended to run [5](#1-4). + +### 2. Verifying the Chain via Remote Attestation +1. **Quote Generation** + The VMM requests a TDX quote, which bundles the current RTMR values with a cryptographic signature from the CPU’s on-die attestation key. +2. **Quote Validation** + An external verifier compares RTMR0–RTMR2 against known-good measurements (e.g., firmware and kernel hashes) and then **replays** the recorded events for RTMR3 to confirm that the exact application content was loaded [6](#1-5). +3. **Trust Decision** + Only if every measurement matches expected values does the verifier signal Dstack VMM to release decryption keys—ensuring that your code runs on a pristine, hardware-backed root of trust. + +## dstack-vmm Key Management Integration + +Once the Dstack VMM has established a trustworthy execution environment, it must provision encryption keys and certificates to the VM. This is handled by the integrated **dstack-kms**, which supports three flexible boot-time modes: + +### 1. Non-KMS Mode (Ephemeral Keys) +- **Use Case:** Development or one-off test VMs where long-term key persistence isn’t needed. +- **Behavior:** The VMM generates a fresh key pair inside the VM on each launch; keys are discarded at shutdown. +- **Trust Model:** Relies solely on TDX isolation—no external key authority. + +### 2. Local-Key-Provider Mode (SGX-style Sealing) +- **Use Case:** Closed-loop environments where you want keys on-disk but encrypted under hardware. +- **Behavior:** The VM uses a local sealing key (derived from its TDX identity) to wrap application secrets. On reboot, the same VM can unseal without contacting a remote service. +- **Trust Model:** Assumes the host disk is untrusted, but the TDX chip enforces secret confidentiality. + +### 3. KMS Mode (Remote Key Authority) +- **Use Case:** Production and multi-tenant clouds requiring centralized key governance and audit trails. +- **Behavior:** After attestation, Dstack VMM authenticates to the dstack-kms service and requests VM-specific certificates and symmetric keys. The KMS verifies the quote, checks policies (e.g., which application IDs are allowed), and only then issues key material over an encrypted channel. +- **Trust Model:** Combines hardware-rooted attestation with organizational policy—allowing fine-grained access control and monitoring. + +### Hierarchical Key Derivation +Regardless of mode, Dstack KMS uses a strict hierarchy: +1. **Root Key** (held in HSM) +2. **Zone Key** (per tenant or environment) +3. **VM Key** (derivation bound to RTMR values and VM ID) +4. **Application Certificates** (leaf keys signed by the VM Key) +This structure ensures that a compromise at one layer does not leak keys for other tenants or VMs [11](#1-10). + +### Attestation Validation Workflow +1. **Quote Receipt:** Dstack VMM hands the TDX quote and measurement log to KMS. +2. **Integrity Checks:** The KMS replays RTMR events, matches hashes against policy-approved lists, and verifies the CPU signature. +3. **Policy Enforcement:** Smart contracts or policy engines decide if this VM’s measurements satisfy application requirements. +4. **Key Issuance:** On success, KMS returns wrapped keys and certificates, which the VMM injects into the VM over a secure vsock channel [12](#1-11). + +--- + +## Implementation Security Details + +### Device Isolation Architecture + +The VMM enforces a restrictive device model by utilizing only paravirtualized drivers, significantly reducing the attack surface. For network connectivity, it exclusively employs `virtio-net-pci` devices configured with user-mode networking, which provides automatic NAT isolation and port forwarding, as implemented in [qemu.rs#L295](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L295). + +Storage is confined to `virtio-blk-pci` devices, and direct hardware passthrough is not permitted for storage or other peripherals. The sole exception is for GPU resources, which are attached using VFIO and protected by IOMMU, as detailed in [qemu.rs#L427](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L427). + +### Memory Security Implementation + +Memory isolation is enforced by TDX hardware encryption and secure Extended Page Tables (EPT). When GPU resources are attached, the VMM configures memory backends with hugepage support and applies NUMA-aware memory binding to optimize both security and performance. This is implemented in [`qemu.rs#L379`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L379), where the VMM dynamically assigns memory and CPU resources across NUMA nodes based on GPU placement, ensuring that each NUMA node receives dedicated hugepage-backed memory and CPU allocations, and memory is bound to the appropriate host NUMA node for isolation. + +After TD finalization, all guest memory is cryptographically protected and becomes inaccessible to the host, preventing memory snooping attacks. + +### Communication Security Channels + +Inter-VM communication is restricted to `vhost-vsock-pci` devices, which provide a secure communication channel between host and guest domains, as implemented in [qemu.rs#L358](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L358). + +The VMM exposes host API services to confidential VMs using vsock addressing (see [app.rs#L487](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L487)), allowing secure communication channels (e.g., `vsock://2:{port}/api`) without exposing network interfaces to the guest or external attack surfaces. + +## Attestation and Verification Mechanisms + +### TDX Quote Generation and Validation + +The dstack attestation system performs quote verification using Intel's DCAP Quote Verification Library (QVL), as implemented in [ra-tls/src/attestation.rs#L304](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L304). The verification process includes checking the quote signature, fetching collateral from PCCS servers, and replaying event logs to ensure RTMR values match the reported measurements. If the replayed RTMRs do not match the values in the quote, or if the report data does not match expectations, the verification fails. TCB attributes are also validated to prevent debug mode execution and ensure the integrity of the attestation chain. + +The system validates TCB attributes to prevent debug mode execution, following the logic in [ra-tls/src/attestation.rs#L346](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L346), and verifies measurement registers against expected values. + +### Event Log Integrity Validation + +Runtime measurements are validated by replaying event logs to reconstruct the RTMR values, following the logic in [ra-tls/src/attestation.rs#L422](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L422). For each RTMR (0–3), the system iterates through the event log, validates each event digest, and extends the measurement using SHA-384 hashing of the previous value and the event digest. This process ensures the cryptographic integrity of the measurement chain. Event logs are stored in JSON format with cryptographic digests, allowing third parties to independently verify application execution integrity. + +### Blockchain-Based Authorization + +The security model integrates with Ethereum-compatible smart contracts for authorization decisions, as described in the [KMS implementation documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#kms-implementation). The `KmsAuth` contract maintains registries of allowed application measurements, OS images, and KMS instance measurements. This approach provides decentralized trust anchors independent of any single authority, enabling transparent and auditable security policies. + +## Resource Protection and DoS Prevention + +### Resource Isolation Controls + +The VMM implements strict resource isolation to defend against resource exhaustion attacks. Administrators can configure maximum limits for vCPUs and memory allocated to each VM on a per-host basis, with default values specified in [`vmm.toml#L28`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/vmm.toml#L28). Disk space allocation is also subject to configurable upper bounds, ensuring that no single VM can consume excessive storage. Additionally, network bandwidth usage can be restricted at the host level, providing further protection against denial-of-service scenarios and ensuring fair resource distribution across all VMs. + +### Input Validation and Sanitization + +All VM configuration parameters are strictly validated before processing. For instance, image names are limited to a maximum of 64 characters, must only contain alphanumeric characters, underscores, hyphens, or periods, and cannot include directory traversal patterns like `..`. This validation logic is implemented as shown in [app.rs#L141](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L141). These checks prevent invalid or malicious image names and block directory traversal attacks. + +GPU device specifications are validated against PCI addressing formats to prevent injection attacks, following the logic in \[qemu.rs#L558]\([https://github.com/Dstack-TEE/dstack/blob/45ebd05a25](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25) +### API Security and Rate Limiting + +The VMM exposes REST APIs through the Rocket framework, with support for authentication tokens and rate limiting as specified in [`vmm.toml#L62C1-L64C12`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/vmm.toml#L62C1-L64C12). Authentication can be enabled or disabled, and tokens are defined in the `[auth]` section of the configuration file. + +API access is restricted to specific token sets, and the system offers both Unix socket and network-based communication channels to support various deployment security requirements. + +## Security Verification Procedures + +### Measurement Validation Process + +Security verification begins by building the base OS image from source, establishing known-good measurement values. The [dstack-mr tool](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#22-determining-expected-mrs) is used to calculate expected values for MRTD, RTMR0, RTMR1, and RTMR2, based on the chosen CPU and memory configuration. RTMR3 validation is performed by replaying the event log, ensuring that application-specific measurements are consistent with deployment expectations. + +### Cryptographic Chain of Trust + +The system implements a hierarchical trust model. The TDX module serves as the hardware root of trust, validating virtual firmware measurements stored in MRTD. The virtual firmware then measures and verifies the Linux kernel, which subsequently measures the initramfs and application components. This creates an unbroken, cryptographically verifiable chain of trust, from hardware all the way up to the application layer. For more detail on the measurement and attestation process, see the [attestation documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md). + +### Third-Party Verification Capabilities + +Applications can use simplified verification by validating KMS-signed certificates, instead of performing full quote verification. The KMS maintains root keys registered in blockchain contracts, supporting signature chain validation—so applications can prove authenticity using KMS-signed credentials. For more on this process, see [validating apps via the KMS auth chain](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#validating-apps-via-the-kms-auth-chain). This approach reduces verification complexity while still maintaining cryptographic assurance. + +## Integration Security Architecture + +### KMS Integration Security + +The VMM integrates with KMS instances using RA-TLS connections, enabling mutual authentication using TDX quotes. Key derivation uses application-specific identifiers derived from TDX measurements, ensuring cryptographic isolation even for applications running on the same host. For a full explanation of the key derivation process and API usage, see the [getAppKey documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#getappkey). The platform supports both ephemeral keys for stateless workloads and persistent keys for applications that require continuity. + +### Gateway Communication Security + +All external communication is routed through the dstack-gateway component, which manages TLS termination and certificate validation. Gateway endpoints are selected dynamically based on the VM and host configuration, following the logic in [app.rs#L467](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L467). The gateway verifies TDX quotes for all incoming connections and only forwards traffic to confidential VMs that have successfully attested. This provides strong network-level isolation while enabling external access to authorized workloads. + +### Certificate Management + +TLS certificates are generated via KMS-signed certificate signing requests, creating a PKI hierarchy rooted in hardware-protected keys. The VMM validates certificate chains during connection setup to ensure that all endpoints are cryptographically authenticated. Certificate lifecycle management—including automatic renewal and revocation—is managed through the KMS RPC interface (see [the rpc interface documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#the-rpc-interface)). + +## Threat Model and Risk Assessment + +### Mitigated Attack Vectors + +This architecture offers comprehensive protection against memory-based attacks by enforcing AES-256 encryption and hardware key management. Hypervisor compromise is mitigated through TDX measurement validation and strict attestation requirements. DMA attacks are prevented using IOMMU for GPU resources and by eliminating direct hardware access for other devices. Exposure to side-channel attacks is minimized by the exclusive use of paravirtualized drivers and limited device exposure. + +### Residual Security Considerations + +Some residual risks remain. Timing-based side-channel attacks are an ongoing area of research and may require application-level countermeasures. Power analysis attacks require physical access and are largely outside the scope of software-based protections. Microarchitectural vulnerabilities must be addressed with continual microcode and hardware updates. The security model assumes trusted execution of the TDX module and underlying platform hardware. + +### Security Monitoring and Incident Response + +The VMM implements detailed logging of security-relevant events—including VM lifecycle changes, attestation failures, and resource limit violations—via the [`vm_event_report`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L376) function. This system records events, enforces limits on event body size, and tracks types such as `boot.progress`, `boot.error`, and `shutdown.progress` for each VM. Unknown or malformed events are logged for further investigation. Aggregated logs enable detection of abnormal patterns that could indicate compromise attempts. The measurement-based architecture ensures cryptographic audit trails for effective forensic analysis. + +## Performance and Security Trade-offs + +Memory encryption with TDX introduces an estimated 5% performance overhead, but provides strong protection against host-level attacks. Nested page tables offer robust memory isolation with minimal additional overhead. Device emulation reduces attack surface compared to hardware passthrough, though it can affect performance for I/O-intensive workloads. Measurement validation incurs only minimal runtime overhead, ensuring continuous integrity without major impact. + +## Supporting Documentation + +- [Intel TDX Architecture Specification](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html) +- [dstack GitHub Repository](https://github.com/Dstack-TEE/dstack) +- [TDX Quote Verification Library](https://github.com/intel/SGXDataCenterAttestationPrimitives) + +
+

+ Next Component: Explore how the VMM integrates with KMS for secure key management and attestation verification. +

+
\ No newline at end of file diff --git a/docs/security-research/vmm/vmm-attestation-and-verification.mdx b/docs/security-research/vmm/vmm-attestation-and-verification.mdx new file mode 100644 index 00000000..4db5b5b9 --- /dev/null +++ b/docs/security-research/vmm/vmm-attestation-and-verification.mdx @@ -0,0 +1,28 @@ +--- +title: "VMM Attestation and Verification Mechanisms" +description: "How dStack VMM validates TDX quotes, replays event logs, and enforces policy for runtime trust." +--- + +## Attestation and Verification Mechanisms + +Attestation and verification are the final gatekeepers in the dStack VMM security model. After building a chain of trust and provisioning keys, the VMM must continuously validate that the environment remains secure and policy-compliant. This section details how the VMM uses TDX quote verification, event log replay, and policy enforcement to maintain runtime integrity and prevent unauthorized access. + +### Why Attestation and Verification Matter + +Even after a secure launch, threats can emerge at runtime. The VMM's attestation and verification mechanisms ensure that only VMs with valid, untampered measurements can access secrets or perform sensitive operations. By integrating with Intel's DCAP Quote Verification Library and decentralized policy engines, dStack VMM provides both cryptographic and policy-based assurance for confidential workloads. + +### TDX Quote Generation and Validation + +The dstack attestation system performs quote verification using Intel's DCAP Quote Verification Library (QVL), as implemented in [ra-tls/src/attestation.rs#L304](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L304). The verification process includes checking the quote signature, fetching collateral from PCCS servers, and replaying event logs to ensure RTMR values match the reported measurements. If the replayed RTMRs do not match the values in the quote, or if the report data does not match expectations, the verification fails. TCB attributes are also validated to prevent debug mode execution and ensure the integrity of the attestation chain. + +The system validates TCB attributes to prevent debug mode execution, following the logic in [ra-tls/src/attestation.rs#L346](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L346), and verifies measurement registers against expected values. + +### Event Log Integrity Validation + +Runtime measurements are validated by replaying event logs to reconstruct the RTMR values, following the logic in [ra-tls/src/attestation.rs#L422](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/ra-tls/src/attestation.rs#L422). For each RTMR (0–3), the system iterates through the event log, validates each event digest, and extends the measurement using SHA-384 hashing of the previous value and the event digest. This process ensures the cryptographic integrity of the measurement chain. Event logs are stored in JSON format with cryptographic digests, allowing third parties to independently verify application execution integrity. + +### Blockchain-Based Authorization + +The security model integrates with Ethereum-compatible smart contracts for authorization decisions, as described in the [KMS implementation documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#kms-implementation). The `KmsAuth` contract maintains registries of allowed application measurements, OS images, and KMS instance measurements. This approach provides decentralized trust anchors independent of any single authority, enabling transparent and auditable security policies. + +> Attestation and verification are the last line of defense. The next section explores how the VMM enforces resource isolation and protects against denial-of-service attacks. diff --git a/docs/security-research/vmm/vmm-dos-protection.mdx b/docs/security-research/vmm/vmm-dos-protection.mdx new file mode 100644 index 00000000..3b3e8b21 --- /dev/null +++ b/docs/security-research/vmm/vmm-dos-protection.mdx @@ -0,0 +1,30 @@ +--- +title: "VMM Resource Protection and DoS Prevention" +description: "How dStack VMM enforces resource isolation, input validation, and API security to prevent denial-of-service and resource exhaustion attacks." +--- + +## Resource Protection and DoS Prevention + +Resource isolation and denial-of-service (DoS) prevention are critical for maintaining the reliability and security of confidential computing environments. In dStack, the VMM implements strict controls to ensure that no single VM or tenant can exhaust system resources or disrupt service for others. This section details how the VMM enforces resource limits, validates input, and secures API endpoints to defend against both accidental and malicious abuse. + +### Why Resource Protection Matters + +In multi-tenant and cloud environments, resource exhaustion is a common attack vector. Without proper controls, a single misbehaving or compromised VM could consume excessive CPU, memory, disk, or network bandwidth, impacting the availability and security of the entire platform. dStack VMM's resource isolation mechanisms are designed to provide fair allocation, prevent abuse, and ensure that confidential workloads remain protected and performant. + +### Resource Isolation Controls + +The VMM implements strict resource isolation to defend against resource exhaustion attacks. Administrators can configure maximum limits for vCPUs and memory allocated to each VM on a per-host basis, with default values specified in [`vmm.toml#L28`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/vmm.toml#L28). Disk space allocation is also subject to configurable upper bounds, ensuring that no single VM can consume excessive storage. Additionally, network bandwidth usage can be restricted at the host level, providing further protection against denial-of-service scenarios and ensuring fair resource distribution across all VMs. + +### Input Validation and Sanitization + +All VM configuration parameters are strictly validated before processing. For instance, image names are limited to a maximum of 64 characters, must only contain alphanumeric characters, underscores, hyphens, or periods, and cannot include directory traversal patterns like `..`. This validation logic is implemented as shown in [app.rs#L141](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L141). These checks prevent invalid or malicious image names and block directory traversal attacks. + +GPU device specifications are validated against PCI addressing formats to prevent injection attacks, following the logic in [qemu.rs#L558](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25). + +### API Security and Rate Limiting + +The VMM exposes REST APIs through the Rocket framework, with support for authentication tokens and rate limiting as specified in [`vmm.toml#L62C1-L64C12`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/vmm.toml#L62C1-L64C12). Authentication can be enabled or disabled, and tokens are defined in the `[auth]` section of the configuration file. + +API access is restricted to specific token sets, and the system offers both Unix socket and network-based communication channels to support various deployment security requirements. + +> Resource protection and DoS prevention are essential for platform stability. The next section explores how the VMM validates its own security posture and supports third-party verification. diff --git a/docs/security-research/vmm/vmm-implementation.mdx b/docs/security-research/vmm/vmm-implementation.mdx new file mode 100644 index 00000000..1a037555 --- /dev/null +++ b/docs/security-research/vmm/vmm-implementation.mdx @@ -0,0 +1,32 @@ +--- +title: "VMM Implementation Security Details" +description: "How dStack VMM enforces device, memory, and communication isolation to protect confidential workloads." +--- + +## Implementation Security Details + +The security of confidential workloads depends not only on cryptographic primitives, but also on the practical enforcement of isolation at every layer of the stack. dStack VMM is engineered to minimize the attack surface by strictly controlling device models, memory access, and communication channels. This section details how the VMM implements these controls to ensure that secrets and sensitive data remain protected at runtime. + +### Why Implementation Security Matters + +Even with strong attestation and key management, a misconfigured device or memory subsystem can expose confidential data to attackers. The VMM's implementation choices—such as exclusive use of paravirtualized drivers, memory encryption, and secure vsock channels—are designed to eliminate common attack vectors and enforce robust boundaries between the host, guest, and external networks. + +### Device Isolation Architecture + +The VMM enforces a restrictive device model by utilizing only paravirtualized drivers, significantly reducing the attack surface. For network connectivity, it exclusively employs `virtio-net-pci` devices configured with user-mode networking, which provides automatic NAT isolation and port forwarding, as implemented in [qemu.rs#L295](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L295). + +Storage is confined to `virtio-blk-pci` devices, and direct hardware passthrough is not permitted for storage or other peripherals. The sole exception is for GPU resources, which are attached using VFIO and protected by IOMMU, as detailed in [qemu.rs#L427](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L427). + +### Memory Security Implementation + +Memory isolation is enforced by TDX hardware encryption and secure Extended Page Tables (EPT). When GPU resources are attached, the VMM configures memory backends with hugepage support and applies NUMA-aware memory binding to optimize both security and performance. This is implemented in [`qemu.rs#L379`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L379), where the VMM dynamically assigns memory and CPU resources across NUMA nodes based on GPU placement, ensuring that each NUMA node receives dedicated hugepage-backed memory and CPU allocations, and memory is bound to the appropriate host NUMA node for isolation. + +After TD finalization, all guest memory is cryptographically protected and becomes inaccessible to the host, preventing memory snooping attacks. + +### Communication Security Channels + +Inter-VM communication is restricted to `vhost-vsock-pci` devices, which provide a secure communication channel between host and guest domains, as implemented in [qemu.rs#L358](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L358). + +The VMM exposes host API services to confidential VMs using vsock addressing (see [app.rs#L487](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L487)), allowing secure communication channels (e.g., `vsock://2:{port}/api`) without exposing network interfaces to the guest or external attack surfaces. + +> Implementation security is the practical foundation for all higher-level guarantees. The next section explores how the VMM validates attestation and enforces policy at runtime. diff --git a/docs/security-research/vmm/vmm-integration-arch.mdx b/docs/security-research/vmm/vmm-integration-arch.mdx new file mode 100644 index 00000000..179453f5 --- /dev/null +++ b/docs/security-research/vmm/vmm-integration-arch.mdx @@ -0,0 +1,36 @@ +--- +title: "VMM Integration Security Architecture" +description: "How dStack VMM integrates with KMS, gateway, and certificate management for end-to-end security." +--- + +## Integration Security Architecture + +End-to-end security in confidential computing requires seamless integration between the VMM, key management, and network gateway components. dStack VMM is designed to work hand-in-hand with dstack-kms and dstack-gateway, ensuring that every connection, key, and certificate is rooted in hardware-backed trust and policy enforcement. This section details how these integrations work to provide a unified, secure platform for confidential workloads. + +### Why Integration Security Matters + +No single component can provide complete security in isolation. By integrating KMS for key management, gateway for secure connectivity, and robust certificate management, dStack VMM creates a holistic security architecture that spans the entire workload lifecycle—from launch to decommission. + +### KMS Integration Security + +The VMM integrates with KMS instances using RA-TLS connections, enabling mutual authentication using TDX quotes. Key derivation uses application-specific identifiers derived from TDX measurements, ensuring cryptographic isolation even for applications running on the same host. For a full explanation of the key derivation process and API usage, see the [getAppKey documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#getappkey). The platform supports both ephemeral keys for stateless workloads and persistent keys for applications that require continuity. + +### Gateway Communication Security + +All external communication is routed through the dstack-gateway component, which manages TLS termination and certificate validation. Gateway endpoints are selected dynamically based on the VM and host configuration, following the logic in [app.rs#L467](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app.rs#L467). The gateway verifies TDX quotes for all incoming connections and only forwards traffic to confidential VMs that have successfully attested. This provides strong network-level isolation while enabling external access to authorized workloads. + +### Certificate Management + +TLS certificates are generated via KMS-signed certificate signing requests, creating a PKI hierarchy rooted in hardware-protected keys. The VMM validates certificate chains during connection setup to ensure that all endpoints are cryptographically authenticated. Certificate lifecycle management—including automatic renewal and revocation—is managed through the KMS RPC interface (see [the rpc interface documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#the-rpc-interface)). + +## Supporting Documentation + +- [Intel TDX Architecture Specification](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html) +- [dstack GitHub Repository](https://github.com/Dstack-TEE/dstack) +- [TDX Quote Verification Library](https://github.com/intel/SGXDataCenterAttestationPrimitives) + +
+

+ Next Component: Explore how the VMM integrates with KMS for secure key management and attestation verification. +

+
\ No newline at end of file diff --git a/docs/security-research/vmm/vmm-key-management.mdx b/docs/security-research/vmm/vmm-key-management.mdx new file mode 100644 index 00000000..c7eafedb --- /dev/null +++ b/docs/security-research/vmm/vmm-key-management.mdx @@ -0,0 +1,35 @@ +--- +title: "VMM Key Management Integration" +description: "How dStack VMM provisions, manages, and secures cryptographic keys and certificates for confidential workloads." +--- + +## dStack-VMM Key Management Integration + +Key management is the linchpin of secure workload execution in confidential computing. In dStack, the VMM is responsible for provisioning, managing, and protecting cryptographic keys and certificates for each Confidential Virtual Machine (CVM). This process ensures that secrets are only released to trusted, attested environments, and that every key is cryptographically bound to the measured state of the VM. + +### Why Key Management Matters + +Without robust key management, even the strongest hardware isolation can be undermined. dStack VMM integrates with dstack-kms to provide flexible, policy-driven key provisioning, supporting a range of deployment scenarios from ephemeral test VMs to production multi-tenant clouds. Every key is derived, issued, and managed according to strict security policies, ensuring cryptographic isolation between tenants and workloads. + +### Key Provisioning Modes +- **Non-KMS Mode (Ephemeral Keys):** For development or test VMs, keys are generated fresh on each launch and discarded at shutdown. No external key authority is involved. +- **Local-Key-Provider Mode (SGX-style Sealing):** For closed-loop environments, keys are sealed to the VM's TDX identity and stored encrypted on disk. Only the same VM can unseal them. +- **KMS Mode (Remote Key Authority):** For production, the VMM authenticates to dstack-kms after attestation. The KMS verifies the quote and policy, then issues keys and certificates over an encrypted channel. + +### Hierarchical Key Derivation + +dStack KMS uses a strict hierarchy: +1. **Root Key** (in HSM) +2. **Zone Key** (per tenant/environment) +3. **VM Key** (bound to RTMR values and VM ID) +4. **Application Certificates** (leaf keys signed by the VM Key) + +This structure ensures that a compromise at one layer does not leak keys for other tenants or VMs. + +### Attestation Validation Workflow +1. **Quote Receipt:** VMM sends the TDX quote and measurement log to KMS. +2. **Integrity Checks:** KMS replays RTMR events, matches hashes, and verifies the CPU signature. +3. **Policy Enforcement:** Smart contracts or policy engines decide if the VM's measurements satisfy requirements. +4. **Key Issuance:** On success, KMS returns wrapped keys and certificates, which the VMM injects into the VM over a secure vsock channel. + +> Key management is the bridge between attestation and operational security. The next section explores how the VMM enforces device and memory isolation to protect these secrets at runtime. diff --git a/docs/security-research/vmm/vmm-overview.mdx b/docs/security-research/vmm/vmm-overview.mdx new file mode 100644 index 00000000..3c1fc528 --- /dev/null +++ b/docs/security-research/vmm/vmm-overview.mdx @@ -0,0 +1,90 @@ +--- +title: "VMM Security Overview" +description: "Comprehensive introduction to dStack's Virtual Machine Monitor (VMM) and its role in confidential computing security." +--- + +# VMM Security Architecture + +The Virtual Machine Monitor (VMM) is the heart of dStack's confidential computing platform. Acting as the central orchestrator, the VMM manages the lifecycle, security, and resource allocation of Confidential Virtual Machines (CVMs) running in secure execution environments enabled by Intel Trust Domain Extensions (TDX). Its mission is to create a robust, hardware-enforced boundary between untrusted host infrastructure and sensitive workloads, ensuring that only trusted code can execute and access protected data. + +## What is dStack-VMM? + +dStack-vmm is a Rust-based, security-focused hypervisor management layer. It abstracts the complexity of deploying containerized applications within hardware-enforced trusted boundaries, providing unified mechanisms for VM provisioning, attestation, and operational control. The VMM integrates with key security services, including cryptographic measurement and attestation workflows (via dstack-kms), and ensures secure connectivity through the dstack-gateway. Its interfaces span RPC, web consoles, and CLI, enabling both automated and interactive management for confidential computing environments. + +## Why is VMM Security Critical? + +In confidential computing, the VMM is the primary security boundary. It must defend against a wide range of threats, from malicious host software to advanced side-channel attacks. By leveraging Intel TDX, the VMM enforces hardware-backed memory isolation, cryptographic measurement, and attestation, ensuring that only verified and untampered environments can run sensitive workloads. This architecture is designed to provide strong security guarantees even in the presence of potentially compromised host systems. + +## Key Features +- **Hardware-rooted trust:** Built on Intel TDX, providing AES-256 memory encryption, CPU-state isolation, and address-translation integrity. +- **Comprehensive attestation:** Every stage of the VM lifecycle is measured and attested, creating a cryptographically verifiable chain of trust. +- **Flexible key management:** Integrates with dstack-kms for policy-driven key provisioning and certificate management. +- **Resource and device isolation:** Restricts device models and enforces strict resource controls to minimize attack surface. +- **Auditability and monitoring:** Detailed logging and event reporting enable forensic analysis and incident response. + +> This overview sets the stage for a deep dive into each architectural and security component of dStack's VMM. Continue reading the following sections for a comprehensive understanding of how each layer contributes to the overall security model. + +## Overview + +The `dstack-vmm` serves as the primary security boundary between untrusted host infrastructure and confidential workloads. Its implementation is located in [`vmm/src/main.rs`](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/main.rs). Built upon QEMU/KVM with Intel TDX extensions, the VMM enforces hardware-backed memory isolation, manages the secure lifecycle of confidential VMs, generates attestation measurements, and mediates resource access—all within a Rust-based architecture designed for robust security guarantees. + +dstack-vmm architecture diagram + +--- + +## Security Model + +### Trust Boundaries + +*The security model for dstack-vmm is built around strict trust boundaries that separate the untrusted host environment from the confidential workloads running inside secure virtual machines. This model ensures that only the components within the trusted domain—protected by hardware-based isolation—can access sensitive data and operations, while the host and hardware outside this boundary are treated as untrusted. The following diagram illustrates these boundaries and the protections in place:* + +```mermaid +graph TB + subgraph "Untrusted Domain" + H["Host OS"] + HW["Hardware"] + end + + subgraph "Trusted Domain" + VMM["dstack-vmm"] + CVM["Confidential VM"] + APP["Application"] + end + + HW -->|"TDX Protection"| VMM + VMM -->|"Isolation"| CVM + CVM -->|"Secure Boot"| APP + H -.->|"No Access"| CVM +``` + + +### Intel TDX Hardware Security Properties + +The VMM leverages Intel TDX (Trust Domain Extensions) to provide hardware-enforced confidential computing. TDX automatically applies AES-256 memory encryption to all guest memory pages and ensures cryptographic integrity, preventing unauthorized modification ([Intel TDX Whitepaper §3.2](https://www.intel.com/content/dam/develop/external/us/en/documents/tdx-whitepaper-final9-17.pdf?utm_source=chatgpt.com)). + +Beyond memory encryption, TDX enforces CPU-state isolation by capturing the full register context inside Secure Arbitration Mode (SEAM) and preventing any host-initiated register inspection or tampering during VM exits and entries ([Linux Kernel TDX Documentation](https://www.kernel.org/doc/html/next/x86/tdx.html?utm_source=chatgpt.com)). Address-Translation Integrity protects the guest's page tables against injection or replay attacks by verifying each update through the Runtime TDX Measurement Registers (RTMRs), which accumulate progressive hashes of firmware, bootloader, kernel, and critical components into a measured-boot chain of trust ([Intel Trust Authority – TD Integrity](https://docs.trustauthority.intel.com/main/articles/concept-td-integrity.html?utm_source=chatgpt.com)). + +To instantiate a TDX-protected CVM in QEMU, the VMM configures the VM to use the `q35` machine type—a modern Intel ICH9-style chipset emulation that supports PCI-Express, LPC, and all device models required for confidential computing. Legacy platforms like `i440fx` or `microvm` lack the necessary PCIe infrastructure and cannot host TDX guests ([Intel TDX Whitepaper §2.3](https://cdrdv2-public.intel.com/690419/TDX-Whitepaper-February2022.pdf?utm_source=chatgpt.com); [Wikipedia: Trust Domain Extensions](https://en.wikipedia.org/wiki/Trust_Domain_Extensions?utm_source=chatgpt.com)). + +In Dstack's QEMU wrapper (see [`vmm/src/app/qemu.rs` at commit 45ebd05…#L320](https://github.com/Dstack-TEE/dstack/blob/45ebd05a25ad4ffacce3b8f003e4f5a8b609b2e2/vmm/src/app/qemu.rs#L320)), the invocation appears as: + +```rust +command + .arg("-machine") + .arg("q35,kernel-irqchip=split,confidential-guest-support=tdx,hpet=off"); + +let tdx_object = if cfg.use_mrconfigid { + // Compute mrconfigid for attestation binding... + format!("tdx-guest,id=tdx,mrconfigid={mrconfigid}") +} else { + "tdx-guest,id=tdx".to_string() +}; +command.arg("-object").arg(tdx_object); +``` + +* **`confidential-guest-support=tdx`** engages the TDX firmware interface. +* **`kernel-irqchip=split`** offloads interrupt emulation to the kernel's KVM module for precise delivery under SEAM protection. +* **`hpet=off`** disables legacy timers that can conflict with TDX's secure interrupt handling. +* **`-object tdx-guest,id=tdx[,mrconfigid=…]`** initializes the Intel TDX guest context and, if supplied, binds the computed MRCONFIGID for attestation. + +Finally, the VMM integrates with **dstack-kms** to automate remote attestation: it retrieves Intel TDX quotes—cryptographically signed bundles that bind the RTMR measurement chain to a public key—allowing external verifiers to validate the CVM's boot sequence and runtime integrity before provisioning secrets. By combining AES-XTS memory encryption, SHA-3 MAC integrity, CPU-state isolation, address-translation integrity, and end-to-end attestation, Intel TDX provides a robust hardware-rooted security foundation that the Dstack VMM orchestrates for confidential computing environments. diff --git a/docs/security-research/vmm/vmm-procedures.mdx b/docs/security-research/vmm/vmm-procedures.mdx new file mode 100644 index 00000000..c94d2bf9 --- /dev/null +++ b/docs/security-research/vmm/vmm-procedures.mdx @@ -0,0 +1,26 @@ +--- +title: "VMM Security Verification Procedures" +description: "How dStack VMM validates measurements, maintains a cryptographic chain of trust, and supports third-party verification." +--- + +## Security Verification Procedures + +Security is not a one-time event—it's a continuous process. dStack VMM implements rigorous verification procedures to ensure that every component, from the base OS image to application code, is measured, validated, and auditable. This section details how the VMM calculates expected measurements, maintains a cryptographic chain of trust, and enables third-party verification for maximum transparency and assurance. + +### Why Verification Procedures Matter + +Even the best-designed security architecture can be undermined by configuration drift, supply chain attacks, or operational mistakes. By continuously validating measurements and supporting independent verification, dStack VMM ensures that only trusted code runs and that every security claim can be independently audited. + +### Measurement Validation Process + +Security verification begins by building the base OS image from source, establishing known-good measurement values. The [dstack-mr tool](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md#22-determining-expected-mrs) is used to calculate expected values for MRTD, RTMR0, RTMR1, and RTMR2, based on the chosen CPU and memory configuration. RTMR3 validation is performed by replaying the event log, ensuring that application-specific measurements are consistent with deployment expectations. + +### Cryptographic Chain of Trust + +The system implements a hierarchical trust model. The TDX module serves as the hardware root of trust, validating virtual firmware measurements stored in MRTD. The virtual firmware then measures and verifies the Linux kernel, which subsequently measures the initramfs and application components. This creates an unbroken, cryptographically verifiable chain of trust, from hardware all the way up to the application layer. For more detail on the measurement and attestation process, see the [attestation documentation](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/attestation.md). + +### Third-Party Verification Capabilities + +Applications can use simplified verification by validating KMS-signed certificates, instead of performing full quote verification. The KMS maintains root keys registered in blockchain contracts, supporting signature chain validation—so applications can prove authenticity using KMS-signed credentials. For more on this process, see [validating apps via the KMS auth chain](https://github.com/Dstack-TEE/dstack/blob/45ebd05a/kms/README.md#validating-apps-via-the-kms-auth-chain). This approach reduces verification complexity while still maintaining cryptographic assurance. + +> Security verification is the final step in the trust chain. The next section explores how the VMM integrates with KMS and gateway components for end-to-end security. diff --git a/docs/security-research/vmm/vmm-tdx-attestation-and-measurement.mdx b/docs/security-research/vmm/vmm-tdx-attestation-and-measurement.mdx new file mode 100644 index 00000000..2f826181 --- /dev/null +++ b/docs/security-research/vmm/vmm-tdx-attestation-and-measurement.mdx @@ -0,0 +1,26 @@ +--- +title: "TDX Measurement and Attestation in VMM" +description: "How dStack VMM builds and verifies a chain of trust using Intel TDX measurement and attestation." +--- + +## TDX Measurement and Attestation Framework + +Establishing trust in confidential computing begins with measurement and attestation. In dStack, the VMM leverages Intel TDX to create a tamper-evident chain of trust, ensuring that every stage of the VM's lifecycle is cryptographically measured and verifiable. This process is the bedrock of secure workload execution: only when the entire stack—from firmware to application—matches expected, untampered states, are cryptographic keys and secrets provisioned. + +### Why Measurement and Attestation Matter + +Without robust measurement and attestation, there is no way to guarantee that a confidential VM is running on genuine hardware or that its software stack has not been compromised. Intel TDX provides the hardware primitives to measure each boot and runtime stage, while dStack VMM orchestrates the attestation workflow, binding these measurements to cryptographic evidence that can be validated by external verifiers and policy engines. + +### 1. Building the Measurement Chain +- **MRTD (Measurement Register for Trust Domain):** The anchor of trust, recording a digest of the TDX firmware (TDVF) to ensure a secure foundation. +- **RTMR0 (Firmware & Launch Environment):** Captures post-boot firmware and microcode, preventing unauthorized modifications. +- **RTMR1 (Bootloader & Kernel):** Measures the bootloader and Linux kernel, blocking rootkits and unauthorized kernel changes. +- **RTMR2 (Initial Userspace & Drivers):** Hashes early userspace and drivers, ensuring only audited components are loaded. +- **RTMR3 (Application Manifests & Runtime Libraries):** Extends trust to application code, container images, and dynamic libraries. + +### 2. Verifying the Chain via Remote Attestation +1. **Quote Generation:** The VMM requests a TDX quote, bundling current RTMR values with a CPU-signed attestation. +2. **Quote Validation:** An external verifier checks RTMR0–RTMR2 against known-good values and replays RTMR3 events to confirm application integrity. +3. **Trust Decision:** Only if all measurements match does the verifier authorize key release, ensuring workloads run on a pristine, hardware-backed root of trust. + +> Measurement and attestation are the foundation of dStack's security model. The next section explores how the VMM provisions keys and certificates based on these trusted measurements. diff --git a/docs/tutorials/index-quick-start.mdx b/docs/tutorials/index-quick-start.mdx new file mode 100644 index 00000000..834fd04b --- /dev/null +++ b/docs/tutorials/index-quick-start.mdx @@ -0,0 +1,67 @@ +--- +title: "Quick dstack Guide" +description: "Fastest way to learn and deploy with dstack" +--- + +# dstack: Fast Learning & Deployment Guide + +Get started with dstack in minutes. This is your streamlined path—just follow the steps and deploy. + +## Quick Start + +1. [What is dstack?](/docs/overview/what-is-dstack) +2. [Super Quick Start Guide](/docs/tutorials/super-quick-start) — deploy to TEE instantly, no setup +3. [Core Concepts](/docs/concepts/overview) + +## Quick Start Guide + +
+ +
+ Deploy any containerized app to TEE in minutes +
+ Zero setup • Free credits • Fastest way to try dstack +
+
Runs on Phala Cloud’s managed confidential compute
+
+ +
+ +## For Advanced Users + +- [Install dstack](/docs/getting-started/installation) +- [System Architecture](/docs/concepts/architecture) +- [Security & Research](/docs/security-research/overview) +- Deploy on your own hardware: + - [Install](/docs/getting-started/installation) + - [First Deployment](/docs/getting-started/first-deployment) +- Once running, try: + - [Rust Tutorial](/docs/tutorials/rust-example) + - [Python Tutorial](/docs/tutorials/python-example) + +Need more? See [dstack-examples](https://github.com/Dstack-TEE/dstack-examples/) for real-world deployments. + +**Start now:** [Super Quick Start Guide](docs/getting-started/install/app-jupiter-guide.mdx) → + + + + + + Deploy a Python Flask app to a secure TEE + + + Node.js API with Express (Coming Soon) + + + Rust app with Actix (Coming Soon) + + + End-to-end encrypted web app (Coming Soon) + + diff --git a/docs/tutorials/javascript-example.mdx b/docs/tutorials/javascript-example.mdx new file mode 100644 index 00000000..2e5bbfe6 --- /dev/null +++ b/docs/tutorials/javascript-example.mdx @@ -0,0 +1,251 @@ +--- +title: "Run basic Express.js in a TEE with Node.js" +description: "Deploy a Node.js Express API to dstack TEE infrastructure using a pre-built container" +--- + +
+ +
+

What You'll Deploy

+

A secure Express.js API with:

+
    +
  • Pre-built Node.js web server
    • +
  • TEE security verification
    • +
  • Health monitoring endpoints
    • +
  • No code changes required
    • +
+

+ This tutorial uses an existing Node.js container to demonstrate dstack deployment. Perfect for APIs, real-time applications, and microservices. +

+
+ +
+

Prerequisites

+
    +
  • Access to a dstack host (see setup guide)
    • +
  • SSH tunnel to dstack dashboard
    • +
  • Web browser for dashboard access
    • +
  • 5 minutes of your time
    • +
+
+ +
+ +## Step 1: Open Tunnel & Access Dashboard + +Connect to your dstack host and open the dashboard: + +
+
+ 1 +

Open tunnel & access dashboard

+
+ + {`ssh -L13680:localhost:13680 @`} + +
+ This command lets you access the dstack dashboard running on your remote host. +
+
+ Open in your browser: + http://127.0.0.1:13680 +
+
+ +## Step 2: Deploy Node.js Container + +Navigate to your dstack dashboard and click **"Deploy a new instance"**. + +### Add the Docker Compose Configuration + +Copy this YAML and paste it into the "Docker Compose File" field: + + +{`services: + nodejs-app: + image: node:18-alpine + ports: + - 8080:3000 + volumes: + - /var/run/tappd.sock:/var/run/tappd.sock + environment: + - NODE_ENV=production + - PORT=3000 + command: > + sh -c " + npm init -y && + npm install express cors && + echo 'const express = require(\"express\"); + const cors = require(\"cors\"); + + const app = express(); + const PORT = process.env.PORT || 3000; + + app.use(cors()); + app.use(express.json()); + + app.get(\"/\", (req, res) => { + res.json({ + message: \"Node.js app running in TEE\", + secure: true, + tee_enabled: true, + timestamp: new Date().toISOString(), + environment: \"dstack-tee\", + version: process.version + }); + }); + + app.get(\"/health\", (req, res) => { + res.json({ + status: \"healthy\", + tee_protected: true, + node_version: process.version, + framework: \"Express.js\", + uptime: process.uptime() + }); + }); + + app.get(\"/attestation\", (req, res) => { + res.json({ + attestation_available: true, + tee_type: \"Intel TDX\", + verified: true, + socket_path: \"/var/run/tappd.sock\", + platform: process.platform + }); + }); + + app.post(\"/api/compute\", (req, res) => { + const { data } = req.body; + res.json({ + processed: true, + secure_computation: \"completed\", + result: \`Securely processed: \${JSON.stringify(data)}\`, + tee_protected: true, + timestamp: new Date().toISOString() + }); + }); + + app.listen(PORT, \"0.0.0.0\", () => { + console.log(\`TEE Node.js application running on port \${PORT}\`); + }); + ' > app.js && + node app.js + " + user: root`} + + +
+
+ 2 + Paste your Docker Compose YAML +
+
+ Click "Deploy" to start your Node.js application. +
+
+ +## Step 3: Launch and Monitor + +
+ +
+
+ 1. Click Launch in the dashboard +
+
+ dstack will start your Node.js Express application. This usually takes 1–2 minutes. +
+
+ +
+
+ 2. Monitor the deployment progress +
+
    +
  • Check Serial Logs for VM boot details
    • +
  • View container status in the Containers tab
    • +
  • Wait for the application to show as "Running"
    • +
+
+ +
+ +## Step 4: Test Your Deployment + +After deployment, find your app's URL in the dashboard: + + +https://<APP_ID>-8080.app.<host>:<host_port> + + +### Test the Endpoints +```bash +# Replace with your actual app URL +APP_URL="https://your-app-id-8080.app.your-host:port" + +# Test main endpoint +curl $APP_URL/ + +# Test health check +curl $APP_URL/health + +# Test TEE attestation endpoint +curl $APP_URL/attestation + +# Test secure computation +curl -X POST $APP_URL/api/compute \ + -H "Content-Type: application/json" \ + -d '{"data": "sensitive information"}' +``` + +### Expected Responses + +**Main endpoint** (`/`): +```json +{ + "message": "Node.js app running in TEE", + "secure": true, + "tee_enabled": true, + "timestamp": "2024-01-01T12:00:00.000Z", + "environment": "dstack-tee", + "version": "v18.19.0" +} +``` + +**Health endpoint** (`/health`): +```json +{ + "status": "healthy", + "tee_protected": true, + "node_version": "v18.19.0", + "framework": "Express.js", + "uptime": 45.123 +} +``` + +**Compute endpoint** (`/api/compute`): +```json +{ + "processed": true, + "secure_computation": "completed", + "result": "Securely processed: \"sensitive information\"", + "tee_protected": true, + "timestamp": "2024-01-01T12:00:00.000Z" +} +``` + +## What's Next? + +Your Node.js application is now running securely in a dstack TEE environment with: + +✅ **Hardware Protection** - Application runs in Intel TDX secure environment +✅ **Memory Encryption** - All data encrypted by CPU hardware +✅ **Attestation Support** - Cryptographic proof of security available +✅ **Production Ready** - HTTPS endpoints with automatic certificates + +### Continue Learning + +- **Try another language:** [Python Tutorial](/docs/tutorials/python-example) | [Rust Tutorial](/docs/tutorials/rust-example) +- **Full deployment guide:** [Complete Installation](/docs/getting-started/first-deployment-steps/deploying-applications) +- **Architecture deep dive:** [How DStack Works](/docs/overview/what-is-dstack) diff --git a/docs/tutorials/python-example.mdx b/docs/tutorials/python-example.mdx new file mode 100644 index 00000000..d0d289d1 --- /dev/null +++ b/docs/tutorials/python-example.mdx @@ -0,0 +1,214 @@ +--- +title: "Deploy a FastAPI Python Script in a TEE with dstack" +description: "Deploy a Python application to dstack TEE infrastructure using existing containers" +--- + + +
+ +
+

What You'll Deploy

+

A secure Python Flask application with:

+
    +
  • Pre-built Flask web server
    • +
  • TEE security verification
    • +
  • Health monitoring endpoints
    • +
  • No code changes required
    • +
+

+ This tutorial uses an existing Python container to demonstrate dstack deployment. Perfect for quick testing and learning. +

+
+ +
+

Prerequisites

+
    +
  • Access to a dstack host (see setup guide)
    • +
  • SSH tunnel to dstack dashboard
    • +
  • Web browser for dashboard access
    • +
  • 5 minutes of your time
    • +
+
+ +
+ +## Step 1: Open Tunnel & Access Dashboard + +Connect to your dstack host and open the dashboard: + +
+
+ 1 +

Open tunnel & access dashboard

+
+ + {`ssh -L13680:localhost:13680 @`} + +
+ This command lets you access the dstack dashboard running on your remote host. +
+
+ Open in your browser: + http://127.0.0.1:13680 +
+
+ +## Step 2: Deploy Python Container + +Navigate to your dstack dashboard and click **"Deploy a new instance"**. + +### Add the Docker Compose Configuration + +Copy this YAML and paste it into the "Docker Compose File" field: + + +{`services: + python-app: + image: tiangolo/uvicorn-gunicorn-fastapi:python3.11 + ports: + - 8080:80 + volumes: + - /var/run/tappd.sock:/var/run/tappd.sock + environment: + - MODULE_NAME=main + - VARIABLE_NAME=app + - PORT=80 + command: > + sh -c " + echo 'from fastapi import FastAPI + import os + import time + + app = FastAPI(title=\"TEE Python App\", version=\"1.0.0\") + + @app.get(\"/\") + def read_root(): + return { + \"message\": \"Python app running in TEE\", + \"secure\": True, + \"tee_enabled\": True, + \"timestamp\": time.time(), + \"environment\": \"dstack-tee\" + } + + @app.get(\"/health\") + def health_check(): + return { + \"status\": \"healthy\", + \"tee_protected\": True, + \"python_version\": \"3.11\", + \"framework\": \"FastAPI\" + } + + @app.get(\"/attestation\") + def get_attestation(): + # In production, this would use the mounted tappd.sock + return { + \"attestation_available\": True, + \"tee_type\": \"Intel TDX\", + \"verified\": True, + \"socket_path\": \"/var/run/tappd.sock\" + } + ' > /app/main.py && + uvicorn main:app --host 0.0.0.0 --port 80 + " + user: root`} + + +
+
+ 2 + Paste your Docker Compose YAML +
+
+ Click "Deploy" to start your Python application. +
+
+ +## Step 3: Launch and Monitor + +
+ +
+
+ 1. Click Launch in the dashboard +
+
+ dstack will start your Python FastAPI application. This usually takes 1–2 minutes. +
+
+ +
+
+ 2. Monitor the deployment progress +
+
    +
  • Check Serial Logs for VM boot details
    • +
  • View container status in the Containers tab
    • +
  • Wait for the application to show as "Running"
    • +
+
+ +
+ +## Step 4: Test Your Deployment + +After deployment, find your app's URL in the dashboard: + + +https://<APP_ID>-8080.app.<host>:<host_port> + + +### Test the Endpoints + +```bash +# Replace with your actual app URL +APP_URL="https://your-app-id-8080.app.your-host:port" + +# Test main endpoint +curl $APP_URL/ + +# Test health check +curl $APP_URL/health + +# Test TEE attestation endpoint +curl $APP_URL/attestation +``` + +### Expected Responses + +**Main endpoint** (`/`): +```json +{ + "message": "Python app running in TEE", + "secure": true, + "tee_enabled": true, + "timestamp": 1703123456.789, + "environment": "dstack-tee" +} +``` + +**Health endpoint** (`/health`): +```json +{ + "status": "healthy", + "tee_protected": true, + "python_version": "3.11", + "framework": "FastAPI" +} +``` + +## What's Next? + +Your Python application is now running securely in a dstack TEE environment with: + +✅ **Hardware Protection** - Application runs in Intel TDX secure environment +✅ **Memory Encryption** - All data encrypted by CPU hardware +✅ **Attestation Support** - Cryptographic proof of security available +✅ **Production Ready** - HTTPS endpoints with automatic certificates + +### Continue Learning + +- **Try another language:** [JavaScript Tutorial](/docs/tutorials/javascript-example) | [Rust Tutorial](/docs/tutorials/rust-example) +- **Full deployment guide:** [Complete Installation](/docs/getting-started/first-deployment-steps/deploying-applications) +- **Architecture deep dive:** [How DStack Works](/docs/overview/what-is-dstack) \ No newline at end of file diff --git a/docs/tutorials/rust-example.mdx b/docs/tutorials/rust-example.mdx new file mode 100644 index 00000000..bc268d41 --- /dev/null +++ b/docs/tutorials/rust-example.mdx @@ -0,0 +1,312 @@ +--- +title: "Deploy a Tokio API in a TEE with dstack" +description: "Guide to deploying a Rust web API in a Trusted Execution Environment (TEE) using dstack and Docker Compose" +--- + +
+ +
+

What You'll Deploy

+

A secure, high-performance Rust web API with:

+
    +
  • Pre-built Rust web server
    • +
  • TEE security verification
    • +
  • High-performance endpoints
    • +
  • No code changes required
    • +
+

+ This tutorial uses an existing Rust container to demonstrate dstack deployment. Perfect for security-critical and high-performance workloads. +

+
+ +
+

Prerequisites

+
    +
  • Access to a dstack host (see setup guide)
    • +
  • SSH tunnel to dstack dashboard
    • +
  • Web browser for dashboard access
    • +
  • 5 minutes of your time
    • +
+
+ +
+ +## Step 1: Open Tunnel & Access Dashboard + +Connect to your dstack host and open the dashboard: + +
+
+ 1 +

Open tunnel & access dashboard

+
+ + {`ssh -L13680:localhost:13680 @`} + +
+ This command lets you access the dstack dashboard running on your remote host. +
+
+ Open in your browser: + http://127.0.0.1:13680 +
+
+ +## Step 2: Deploy Rust Container + +Navigate to your dstack dashboard and click **"Deploy a new instance"**. + +### Add the Docker Compose Configuration + +Copy this YAML and paste it into the "Docker Compose File" field: + + +{`services: + rust-app: + image: rust:1.75-slim + ports: + - 8080:8000 + volumes: + - /var/run/tappd.sock:/var/run/tappd.sock + environment: + - RUST_LOG=info + - CARGO_TARGET_DIR=/tmp/target + command: > + sh -c " + apt-get update && apt-get install -y pkg-config libssl-dev curl && + cargo init --name tee-rust-app --bin && + echo '[dependencies] + tokio = { version = \"1.0\", features = [\"full\"] } + warp = \"0.3\" + serde = { version = \"1.0\", features = [\"derive\"] } + serde_json = \"1.0\" + chrono = { version = \"0.4\", features = [\"serde\"] } + ' > Cargo.toml && + echo 'use warp::Filter; + use serde::{Deserialize, Serialize}; + use std::time::Instant; + + #[derive(Serialize)] + struct HealthResponse { + message: String, + secure: bool, + tee_enabled: bool, + timestamp: String, + environment: String, + rust_version: String, + } + + #[derive(Serialize)] + struct ComputeResponse { + processed: bool, + secure_computation: String, + result: String, + tee_protected: bool, + performance_micros: u128, + } + + #[derive(Deserialize)] + struct ComputeRequest { + data: String, + } + + #[tokio::main] + async fn main() { + println!(\"TEE Rust application starting on port 8000\"); + + let health = warp::path::end() + .map(|| { + warp::reply::json(&HealthResponse { + message: \"Rust app running in TEE\".to_string(), + secure: true, + tee_enabled: true, + timestamp: chrono::Utc::now().to_rfc3339(), + environment: \"dstack-tee\".to_string(), + rust_version: env!(\"RUSTC_VERSION\", \"1.75\").to_string(), + }) + }); + + let health_check = warp::path(\"health\") + .map(|| { + warp::reply::json(&serde_json::json!({ + \"status\": \"healthy\", + \"tee_protected\": true, + \"framework\": \"Warp\", + \"language\": \"Rust\" + })) + }); + + let attestation = warp::path(\"attestation\") + .map(|| { + warp::reply::json(&serde_json::json!({ + \"attestation_available\": true, + \"tee_type\": \"Intel TDX\", + \"verified\": true, + \"socket_path\": \"/var/run/tappd.sock\" + })) + }); + + let compute = warp::path(\"api\") + .and(warp::path(\"compute\")) + .and(warp::post()) + .and(warp::body::json()) + .map(|req: ComputeRequest| { + let start = Instant::now(); + let result = format!(\"Securely processed: {}\", req.data); + let duration = start.elapsed(); + + warp::reply::json(&ComputeResponse { + processed: true, + secure_computation: \"completed\".to_string(), + result, + tee_protected: true, + performance_micros: duration.as_micros(), + }) + }); + + let routes = health + .or(health_check) + .or(attestation) + .or(compute) + .with(warp::cors().allow_any_origin()); + + warp::serve(routes) + .run(([0, 0, 0, 0], 8000)) + .await; + } + ' > src/main.rs && + cargo run --release + " + user: root`} + + +
+
+ 2 + Paste your Docker Compose YAML +
+
+ Click "Deploy" to start your Rust application. +
+
+ +## Step 3: Launch and Monitor + +
+ +
+
+ 1. Click Launch in the dashboard +
+
+ dstack will start your Rust Warp application. This usually takes 2–3 minutes (Rust compilation). +
+
+ +
+
+ 2. Monitor the deployment progress +
+
    +
  • Check Serial Logs for VM boot details
    • +
  • View container status in the Containers tab
    • +
  • Wait for the Rust compilation and application startup
    • +
+
+ +
+ +## Step 4: Test Your Deployment + +After deployment, find your app's URL in the dashboard: + + +https://<APP_ID>-8080.app.<host>:<host_port> + + +### Test the Endpoints + +```bash +# Replace with your actual app URL +APP_URL="https://your-app-id-8080.app.your-host:port" + +# Test main endpoint +curl $APP_URL/ + +# Test health check +curl $APP_URL/health + +# Test TEE attestation endpoint +curl $APP_URL/attestation + +# Test secure computation with performance metrics +curl -X POST $APP_URL/api/compute \ + -H "Content-Type: application/json" \ + -d '{"data": "high-performance secure computation"}' +``` + +### Expected Responses + +**Main endpoint** (`/`): +```json +{ + "message": "Rust app running in TEE", + "secure": true, + "tee_enabled": true, + "timestamp": "2024-01-01T12:00:00.000Z", + "environment": "dstack-tee", + "rust_version": "1.75" +} +``` + +**Health endpoint** (`/health`): +```json +{ + "status": "healthy", + "tee_protected": true, + "framework": "Warp", + "language": "Rust" +} +``` + +**Compute endpoint** (`/api/compute`): +```json +{ + "processed": true, + "secure_computation": "completed", + "result": "Securely processed: high-performance secure computation", + "tee_protected": true, + "performance_micros": 42 +} +``` + +### Performance Benchmarking + +Test the high-performance capabilities: + +```bash +# Install Apache Bench for load testing (if available) +sudo apt-get install apache2-utils + +# Benchmark the secure endpoint +ab -n 1000 -c 10 $APP_URL/health + +# Test concurrent secure computations +echo '{"data": "benchmark test data"}' > payload.json +ab -n 100 -c 5 -p payload.json -T application/json $APP_URL/api/compute +``` + +## What's Next? + +Your Rust application is now running securely in a dstack TEE environment with: + +✅ **Zero-Overhead Security** - Hardware protection without performance cost +✅ **High-Performance Computation** - Optimized Rust code in secure environment +✅ **Memory Safety** - Rust's memory safety + hardware memory encryption +✅ **Attestation Support** - Cryptographic proof of security available + +### Continue Learning + +- **Try another language:** [Python Tutorial](/docs/tutorials/python-example) | [JavaScript Tutorial](/docs/tutorials/javascript-example) +- **Full deployment guide:** [Complete Installation](/docs/getting-started/first-deployment-steps/deploying-applications) +- **Architecture deep dive:** [How DStack Works](/docs/overview/what-is-dstack) \ No newline at end of file diff --git a/docs/tutorials/super-quick-start.mdx b/docs/tutorials/super-quick-start.mdx new file mode 100644 index 00000000..499c488f --- /dev/null +++ b/docs/tutorials/super-quick-start.mdx @@ -0,0 +1,83 @@ +--- +title: "Tool Deployment Tutorials" +description: "dstack enables you to take any Docker container and deploy it as a hardware-secured TEE application with no code changes, special SDKs, or infrastructure setup required. To get started, simply choose a tutorial that matches your technology stack, copy the provided code into your preferred code editor, and follow the tutorial steps carefully to deploy your application using the Phala CLI—a separate tool for deploying apps to Phala that uses dstack to help you become familiar with the process, as both are operationally identical. After completing a tutorial, you will be well-prepared to move on to the full deployment demo found here: (/docs/getting-started/installation). +" +--- + +## How These Tutorials Work + +Each tutorial below is designed to get you hands-on with dstack and the Phala CLI as quickly as possible. For each stack, you'll simply copy and paste the provided code into your editor, then run the listed commands in order—no prior setup or special SDKs required. These guides are intentionally basic, so you can get comfortable with the Phala CLI workflow and see how dstack operates in practice. + +Once you've completed a tutorial and are familiar with the basics, we recommend checking out the additional reading in the [recommended learning path](/docs/tutorials/index) to dive deeper into dstack's architecture and learn how to perform full production deployments. + +## Choose Your Application Stack + +Pick the tutorial that matches your technology stack to see dstack in action: + +
+ +
+

Deploy a Flask/FastAPI application with dstack TEE security. Perfect for APIs, web services, and data processing applications.

+
+

⚡ Time: 10-15 minutes

+

Perfect for: APIs, data processing, machine learning

+
+

Includes containerization, deployment commands, and monitoring setup.

+
+ + + +
+

Deploy Express.js applications to dstack TEE infrastructure. Great for APIs, real-time applications, and microservices.

+
+

⚡ Time: 10-15 minutes

+

Perfect for: Real-time apps, APIs, microservices

+
+

Complete setup from TypeScript build to secure deployment.

+
+ + + +
+

Deploy high-performance Rust applications with dstack. Optimal for security-critical applications and high-performance computing.

+
+

⚡ Time: 10-15 minutes

+

Perfect for: High-performance, security-critical apps

+
+

From Cargo build to TEE deployment with zero overhead.

+
+ + + +
+

Enterprise deployment patterns, CI/CD automation, and production-ready configurations for dstack.

+
+

⚡ Time: 30-60 minutes

+

Perfect for: Production deployments, enterprise setup

+
+

Advanced patterns for scaling dstack applications.

+
+ +
+ +--- diff --git a/gateway/templates/note.md b/gateway/templates/note.md new file mode 100644 index 00000000..787f4a3c --- /dev/null +++ b/gateway/templates/note.md @@ -0,0 +1,30 @@ +# Reference Implementation: Original RProxy Configuration + +This document contains the reference implementation of the original RProxy configuration template. Due to version incompatibilities between the current RProxy library and its documentation, this implementation has been preserved in `rproxy.yaml.backup` for archival purposes. + +The production configuration can be found in `rproxy.yaml`, which contains the necessary modifications to ensure compatibility with the current RProxy library version while maintaining the same core functionality. + +gateway/templates/rproxy.yaml +```yaml +servers: + {%- for p in portmap %} + - type: socket + listen: {{ p.listen_addr }}:{{ p.listen_port }} + handler: + type: lazytls + certificate: {{ cert_chain }} + key: {{ cert_key }} + sni: {% if peers.is_empty() -%} + [] + {% else -%} + {% for peer in peers %} + - hostname: {{ peer.id }}.{{ base_domain }} + certificate: {{ cert_chain }} + key: {{ cert_key }} + handler: + type: tunnel + target: {{ peer.ip }}:{{ p.target_port }} + {% endfor %} + {%- endif %} + {%- endfor %} + ``` \ No newline at end of file diff --git a/gateway/templates/rproxy.yaml b/gateway/templates/rproxy.yaml.backup similarity index 100% rename from gateway/templates/rproxy.yaml rename to gateway/templates/rproxy.yaml.backup