Merge pull request #263 from Dstack-TEE/rust-sdk-tappd

rust-sdk: Add support for legacy TappdClient

Author: kvinwang

.github/workflows/sdk.yaml

@@ -0,0 +1,26 @@
+name: SDK tests
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ master, next, dev-* ]
+  pull_request:
+    branches: [ master, next, dev-* ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  sdk-tests:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Rust
+      uses: dtolnay/[email protected]
+      with:
+        components: clippy, rustfmt
+
+    - name: SDK tests
+      run: cd sdk && ./run-tests.sh

Cargo.lock

@@ -6,16 +6,15 @@ set -e
 pushd sdk/simulator
 ./dstack-simulator &
 SIMULATOR_PID=$!
+trap "kill $SIMULATOR_PID 2>/dev/null || true" EXIT
 echo "Simulator process (PID: $SIMULATOR_PID) started."
 popd
 
 export DSTACK_SIMULATOR_ENDPOINT=$(realpath sdk/simulator/dstack.sock)
+export TAPPD_SIMULATOR_ENDPOINT=$(realpath sdk/simulator/tappd.sock)
 
 echo "DSTACK_SIMULATOR_ENDPOINT: $DSTACK_SIMULATOR_ENDPOINT"
+echo "TAPPD_SIMULATOR_ENDPOINT: $TAPPD_SIMULATOR_ENDPOINT"
 
 # Run the tests
 cargo test
-
-# Kill the simulator after tests finish
-kill $SIMULATOR_PID
-echo "Simulator process (PID: $SIMULATOR_PID) terminated."

run-tests.sh

@@ -13,7 +13,9 @@ trap "kill $SIMULATOR_PID 2>/dev/null || true" EXIT
 popd
 
 pushd rust/
-cargo test
+cargo test -- --show-output
+cargo run --example tappd_client_usage
+cargo run --example dstack_client_usage
 popd
 
 pushd go/

sdk/run-tests.sh

@@ -10,13 +10,14 @@ authors = ["Encifher <[email protected]>"]
 alloy = { workspace = true, features = ["signers", "signer-local"] }
 anyhow.workspace = true
 bon.workspace = true
-hex.workspace = true 
-http.workspace = true 
+hex.workspace = true
+http.workspace = true
 http-client-unix-domain-socket = "0.1.1"
 reqwest = { workspace = true, features = ["json"] }
-serde.workspace = true 
-serde_json.workspace = true 
-sha2.workspace = true 
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+x509-parser.workspace = true
 
 [dev-dependencies]
 dcap-qvl.workspace = true

sdk/rust/Cargo.toml

@@ -1,6 +1,6 @@
 # Dstack Crate
 
-This crate provides a rust client for communicating with the dstack server, which is available inside dstack.
+This crate provides rust clients for communicating with both the current dstack server and the legacy tappd service, which are available inside dstack.
 
 ## Installation
 
@@ -11,8 +11,10 @@ dstack-rust = { git = "https://github.com/Dstack-TEE/dstack.git", package = "dst
 
 ## Basic Usage
 
+### DstackClient (Current API)
+
 ```rust
-use dstack_sdk::DstackClient;
+use dstack_sdk::dstack_client::DstackClient;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -40,46 +42,104 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+### TappdClient (Legacy API)
+
+```rust
+use dstack_sdk::tappd_client::TappdClient;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = TappdClient::new(None); // Uses env var or default to Unix socket
+
+    // Get system info
+    let info = client.info().await?;
+    println!("Instance ID: {}", info.instance_id);
+    println!("App Name: {}", info.app_name);
+
+    // Derive a key
+    let key_resp = client.derive_key("my-app").await?;
+    println!("Key: {}", key_resp.key);
+    println!("Certificate Chain: {:?}", key_resp.certificate_chain);
+
+    // Decode the key to bytes (extracts raw ECDSA P-256 private key - 32 bytes)
+    let key_bytes = key_resp.to_bytes()?;
+    println!("ECDSA P-256 private key bytes (32 bytes): {:?}", key_bytes.len());
+
+    // Generate quote (exactly 64 bytes of report data required)
+    let mut report_data = b"test-data".to_vec();
+    report_data.resize(64, 0); // Pad to 64 bytes
+    let quote_resp = client.get_quote(report_data).await?;
+    println!("Quote: {}", quote_resp.quote);
+    let rtmrs = quote_resp.replay_rtmrs()?;
+    println!("Replayed RTMRs: {:?}", rtmrs);
+
+    Ok(())
+}
+```
+
 ## Features
-### Initialization
+
+### DstackClient Initialization
 
 ```rust
 let client = DstackClient::new(Some("http://localhost:8000"));
 ```
 - `endpoint`: Optional HTTP URL or Unix socket path (`/var/run/dstack.sock` by default)
-
 - Will use the `DSTACK_SIMULATOR_ENDPOINT` environment variable if set
 
-## Methods
+### TappdClient Initialization (Legacy API)
 
-### `info(): InfoResponse`
+```rust
+let client = TappdClient::new(Some("/var/run/tappd.sock"));
+```
+- `endpoint`: Optional HTTP URL or Unix socket path (`/var/run/tappd.sock` by default)
+- Will use the `TAPPD_SIMULATOR_ENDPOINT` environment variable if set
+- Supports the legacy tappd.sock API for backwards compatibility
 
-Fetches metadata and measurements about the CVM instance.
+## API Methods
 
-### `get_key(path: Option<String>, purpose: Option<String>) -> GetKeyResponse`
+### DstackClient Methods
 
-Derives a key for a specified path and optional purpose.
+#### `info(): InfoResponse`
+Fetches metadata and measurements about the CVM instance.
 
+#### `get_key(path: Option<String>, purpose: Option<String>) -> GetKeyResponse`
+Derives a key for a specified path and optional purpose.
 - `key`: Private key in hex format
-
 - `signature_chain`: Vec of X.509 certificate chain entries
 
-### `get_quote(report_data: Vec<u8>) -> GetQuoteResponse`
-
+#### `get_quote(report_data: Vec<u8>) -> GetQuoteResponse`
 Generates a TDX quote with a custom 64-byte payload.
-
 - `quote`: Hex-encoded quote
-
 - `event_log`: Serialized list of events
-
 - `replay_rtmrs()`: Reconstructs RTMR values from the event log
 
-### `emit_event(event: String, payload: Vec<u8>)`
+#### `emit_event(event: String, payload: Vec<u8>)`
 Sends an event log with associated binary payload to the runtime.
 
-### `get_tls_key(...) -> GetTlsKeyResponse`
+#### `get_tls_key(...) -> GetTlsKeyResponse`
 Requests a key and X.509 certificate chain for RA-TLS or server/client authentication.
 
+### TappdClient Methods (Legacy API)
+
+#### `info(): TappdInfoResponse`
+Fetches metadata and measurements about the CVM instance.
+
+#### `derive_key(path: &str) -> DeriveKeyResponse`
+Derives a key for a specified path.
+- `key`: ECDSA P-256 private key in PEM format
+- `certificate_chain`: Vec of X.509 certificate chain entries
+- `to_bytes()`: Extracts and returns the raw ECDSA P-256 private key bytes (32 bytes)
+
+#### `derive_key_with_subject(path: &str, subject: &str) -> DeriveKeyResponse`
+Derives a key with a custom certificate subject.
+
+#### `derive_key_with_subject_and_alt_names(path: &str, subject: Option<&str>, alt_names: Option<Vec<String>>) -> DeriveKeyResponse`
+Derives a key with full certificate customization.
+
+#### `get_quote(report_data: Vec<u8>) -> TdxQuoteResponse`
+Generates a TDX quote with exactly 64 bytes of raw report data.
+
 ### Structures
 - `GetKeyResponse`: Holds derived key and signature chain
 
@@ -104,7 +164,20 @@ cd dstack/sdk/simulator
 Set the endpoint in your environment:
 
 ```
-export DSTACK_SIMULATOR_ENDPOINT=http://localhost:8000
+export DSTACK_SIMULATOR_ENDPOINT=/path/to/dstack-simulator/dstack.sock
+```
+
+## Examples
+
+See the `examples/` directory for comprehensive usage examples:
+
+- `examples/dstack_client_usage.rs` - Complete example using the current DstackClient API
+- `examples/tappd_client_usage.rs` - Complete example using the legacy TappdClient API
+
+Run examples with:
+```bash
+cargo run --example dstack_client_usage
+cargo run --example tappd_client_usage
 ```
 
 ## License

sdk/rust/README.md

@@ -0,0 +1,113 @@
+use dstack_sdk::dstack_client::{DstackClient, TlsKeyConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Create a DstackClient with default endpoint (/var/run/dstack.sock)
+    let client = DstackClient::new(None);
+
+    // Or create with a custom endpoint
+    // let client = DstackClient::new(Some("/custom/path/dstack.sock"));
+
+    // Or create with HTTP endpoint for simulator
+    // let client = DstackClient::new(Some("http://localhost:8000"));
+
+    println!("DstackClient created successfully!");
+
+    // Example usage (these will fail without a running dstack service):
+
+    // 1. Get system info
+    let info = client.info().await?;
+    println!("System info retrieved successfully!");
+    println!("  App ID: {}", info.app_id);
+    println!("  Instance ID: {}", info.instance_id);
+    println!("  App Name: {}", info.app_name);
+    println!("  Device ID: {}", info.device_id);
+    println!("  Compose Hash: {}", info.compose_hash);
+    println!("  TCB Info - MRTD: {}", info.tcb_info.mrtd);
+    println!("  TCB Info - RTMR0: {}", info.tcb_info.rtmr0);
+
+    // 2. Derive a key
+    let response = client
+        .get_key(Some("my-app".to_string()), Some("encryption".to_string()))
+        .await?;
+    println!("Key derived successfully!");
+    println!("  Key length: {}", response.key.len());
+    println!(
+        "  Signature chain length: {}",
+        response.signature_chain.len()
+    );
+
+    // Decode the key
+    let key_bytes = response.decode_key()?;
+    println!("  Decoded key bytes length: {}", key_bytes.len());
+
+    // 3. Generate TDX quote
+    let report_data = b"Hello, dstack world!".to_vec();
+    let response = client.get_quote(report_data).await?;
+    println!("TDX quote generated successfully!");
+    println!("  Quote length: {}", response.quote.len());
+    println!("  Event log length: {}", response.event_log.len());
+
+    // Decode the quote
+    let quote_bytes = response.decode_quote()?;
+    println!("  Decoded quote bytes length: {}", quote_bytes.len());
+
+    // Replay RTMRs from event log
+    let rtmrs = response.replay_rtmrs()?;
+    println!("  Replayed RTMRs: {} entries", rtmrs.len());
+    for (idx, rtmr) in rtmrs.iter() {
+        println!("    RTMR{}: {}", idx, rtmr);
+    }
+
+    // 4. Emit an event
+    let event_payload = b"Application started successfully".to_vec();
+    client
+        .emit_event("AppStart".to_string(), event_payload)
+        .await?;
+    println!("Event emitted successfully!");
+
+    // 5. Get TLS key for server authentication
+    let tls_config = TlsKeyConfig::builder()
+        .subject("my-app.example.com")
+        .alt_names(vec![
+            "www.my-app.com".to_string(),
+            "api.my-app.com".to_string(),
+        ])
+        .usage_server_auth(true)
+        .usage_client_auth(false)
+        .usage_ra_tls(true)
+        .build();
+
+    let response = client.get_tls_key(tls_config).await?;
+    println!("TLS key generated successfully!");
+    println!("  Key length: {}", response.key.len());
+    println!(
+        "  Certificate chain length: {}",
+        response.certificate_chain.len()
+    );
+
+    // 6. Get a simple key without purpose
+    let response = client.get_key(Some("simple-key".to_string()), None).await?;
+    println!("Simple key derived successfully!");
+    println!("  Key: {}", response.key);
+
+    // 7. Generate quote with minimal report data
+    let minimal_data = vec![0x01, 0x02, 0x03, 0x04];
+    let response = client.get_quote(minimal_data).await?;
+    println!("Minimal quote generated successfully!");
+    println!("  Quote length: {}", response.quote.len());
+    println!("  Event log length: {}", response.event_log.len());
+
+    // Parse and display event log
+    let events = response.decode_event_log()?;
+    println!("  Event log contains {} events", events.len());
+    for (i, event) in events.iter().enumerate().take(3) {
+        // Show first 3 events
+        println!(
+            "    Event {}: IMR={}, Type={}, Event='{}'",
+            i, event.imr, event.event_type, event.event
+        );
+    }
+
+    Ok(())
+}