Skip to content

Latest commit

 

History

History
321 lines (254 loc) · 8.63 KB

api.md

File metadata and controls

321 lines (254 loc) · 8.63 KB

dstack Guest Agent RPC API Documentation

This document describes the REST API endpoints for the dstack Guest Agent RPC service.

Base URL

The dstack Guest Agent listens on a Unix domain socket at /var/run/dstack.sock. All API requests should be made to this socket using the --unix-socket flag with curl.

Make sure to map the Unix socket in your Docker Compose file:

services:
  jupyter:
    image: quay.io/jupyter/base-notebook
    volumes:
      - /var/run/dstack.sock:/var/run/dstack.sock

Endpoints

1. Get TLS Key

Derives a cryptographic key and returns it along with its TLS certificate chain. This API can be used to generate a TLS key/certificate for RA-TLS.

Endpoint: /GetTlsKey

Request Parameters:

Field Type Description Example
subject string The subject name for the certificate "example.com"
alt_names array of strings List of Subject Alternative Names (SANs) for the certificate ["www.example.com", "api.example.com"]
usage_ra_tls boolean Whether to include quote in the certificate for RA-TLS true
usage_server_auth boolean Enable certificate for server authentication true
usage_client_auth boolean Enable certificate for client authentication false
not_before uint64 Certificate validity start time as seconds since UNIX epoch 0
not_after uint64 Certificate validity end time as seconds since UNIX epoch 0
with_app_info boolean Whether to include app info in the certificate false

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/GetTlsKey \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "example.com",
    "alt_names": ["www.example.com", "api.example.com"],
    "usage_ra_tls": true,
    "usage_server_auth": true,
    "usage_client_auth": false
  }'

Response:

{
  "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "certificate_chain": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  ]
}

2. Get Key

Generates an ECDSA key using the k256 elliptic curve, derived from the application key, and returns both the key and its signature chain. Sutable for ETH key generation.

Endpoint: /GetKey

Request Parameters:

Field Type Description Example
path string Path for the key "my/key/path"
purpose string Purpose for the key. Can be any string. This is used in the signature chain. "signing"
algorithm string Either secp256k1 or ed25519. Defaults to secp256k1 ed25519

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/GetKey \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "my/key/path",
    "purpose": "signing",
    "algorithm": "ed25519"
  }'

Or

curl --unix-socket /var/run/dstack.sock http://dstack/GetKey?path=my/key/path&purpose=signing&algorithm=ed25519

Response:

{
  "key": "<hex-encoded-key>",
  "signature_chain": [
    "<hex-encoded-signature-1>",
    "<hex-encoded-signature-2>"
  ]
}

3. Get Quote

Generates a TDX quote with given plain report data.

Endpoint: /GetQuote

Request Parameters:

Field Type Description Example
report_data string Report data of max length 64 bytes. Padding with 0s if less than 64 bytes. "1234deadbeaf"

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/GetQuote \
  -H 'Content-Type: application/json' \
  -d '{
    "report_data": "1234deadbeaf"
  }'

Or

curl --unix-socket /var/run/dstack.sock http://dstack/GetQuote?report_data=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Response:

{
  "quote": "<hex-encoded-quote>",
  "event_log": "<json-event-log>",
  "report_data": "<hex-encoded-report-data>",
  "vm_config": "<json-vm-config-string>"
}

Note on Event Log: The event_log field contains a JSON array of TDX event log entries. For RTMR 0-2 (boot-time measurements), only the digest is included; the payload is stripped to reduce response size. For RTMR3 (runtime measurements), both digest and payload are included. To verify the event log, submit it along with the quote to the verifier service.

4. Get Info

Retrieves worker information.

Endpoint: /Info

Example:

curl --unix-socket /var/run/dstack.sock http://dstack/Info

Response:

{
  "app_id": "<hex-encoded-app-id>",
  "instance_id": "<hex-encoded-instance-id>",
  "app_cert": "<certificate-string>",
  "tcb_info": "<tcb-info-string>",
  "app_name": "my-app",
  "device_id": "<hex-encoded-device-id>",
  "mr_aggregated": "<hex-encoded-mr-aggregated>",
  "os_image_hash": "<hex-encoded-os-image-hash>",
  "key_provider_info": "<key-provider-info-string>",
  "compose_hash": "<hex-encoded-compose-hash>",
  "vm_config": "<json-vm-config-string>"
}

5. Emit Event

Emit an event to be extended to RTMR3 on TDX platform. This API requires dstack OS 0.5.0 or later.

Endpoint: /EmitEvent

Request Parameters:

Field Type Description Example
event string The event name "custom-event"
payload string Hex-encoded payload data "deadbeef"

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/EmitEvent \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "custom-event",
    "payload": "deadbeef"
  }'

Response: Empty response with HTTP 200 status code on success.

6. Sign (not yet released)

Signs a payload.

Endpoint: /Sign

Request Parameters:

Field Type Description Example
algorithm string ed25519, secp256k1_prehashed or secp256k1 ed25519
data string Hex-encoded payload data deadbeef

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/Sign \
  -H 'Content-Type: application/json' \
  -d '{
    "algorithm": "ed25519",
    "data": "deadbeef"
  }'

Response:

{
  "signature": "<hex-encoded-signature>",
  "signature_chain": [
    "<hex-encoded-signature-1>",
    "<hex-encoded-signature-2>",
    "<hex-encoded-signature-3>"
  ]
  "public_key": "<hex-encoded-public-key>"
}

7. Verify (not yet released)

Verifies a signature.

Endpoint: /Verify

Request Parameters:

Field Type Description Example
algorithm string ed25519, secp256k1_prehashed or secp256k1 ed25519
data string Hex-encoded payload data deadbeef
signature string Hex-encoded signature deadbeef
public_key string Hex-encoded public key deadbeef

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/Verify \
  -H 'Content-Type: application/json' \
  -d '{
    "algorithm": "ed25519",
    "data": "deadbeef",
    "signature": "deadbeef",
    "public_key": "deadbeef"
  }'

Response:

{
  "valid": "<true|false>"
}

8. Attest

Generates a versioned attestation with the given report data. Returns a dstack-defined attestation format that supports different attestation modes across platforms. You can submit the returned attestation directly to the verifier /verify endpoint.

Endpoint: /Attest

Request Parameters:

Field Type Description Example
report_data string Report data of max length 64 bytes. Padding with 0s if less than 64 bytes. "1234deadbeaf"

Example:

curl --unix-socket /var/run/dstack.sock -X POST \
  http://dstack/Attest \
  -H 'Content-Type: application/json' \
  -d '{
    "report_data": "1234deadbeaf"
  }'

Or

curl --unix-socket /var/run/dstack.sock http://dstack/Attest?report_data=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Response:

{
  "attestation": "<hex-encoded-attestation>"
}

Error Responses

All endpoints may return the following HTTP status codes:

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 500 Internal Server Error: Server-side error

Error responses will include a JSON body with error details:

{
  "error": "Error description"
}