Skip to content

Commit 4126127

Browse files
kvinwangkvinwang
authored
Merge pull request #151 from Dstack-TEE/api-doc
Add client agent API docs
2 parents 10ed752 + 417b2fa commit 4126127

File tree

2 files changed

+396
-0
lines changed

2 files changed

+396
-0
lines changed

‎sdk/curl/api-tappd.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# DStack Tappd RPC API Documentation (Legacy)
2+
3+
This document describes the legacy REST API endpoints for the DStack Tappd service. These APIs are deprecated as of version 0.4.2. For newer versions, please refer to [api.md](api.md) which contains the current API documentation.
4+
5+
## Base URL
6+
7+
The DStack Tappd service listens on a Unix domain socket at `/var/run/tappd.sock`. All API requests should be made to this socket using the `--unix-socket` flag with curl.
8+
9+
Make sure to map the Unix socket in your Docker Compose file:
10+
11+
```yaml
12+
services:
13+
jupyter:
14+
image: quay.io/jupyter/base-notebook
15+
volumes:
16+
- /var/run/tappd.sock:/var/run/tappd.sock
17+
```
18+
19+
## Endpoints
20+
21+
### 1. Derive Key
22+
23+
Derives a cryptographic key from the specified key path and returns it along with its certificate chain.
24+
25+
**Endpoint:** `/prpc/Tappd.DeriveKey`
26+
27+
**Request Parameters:**
28+
29+
| Field | Type | Description | Example |
30+
|-------|------|-------------|----------|
31+
| `path` | string | Path used to derive the private key | `"my/key/path"` |
32+
| `subject` | string | The subject name for the certificate | `"example.com"` |
33+
| `alt_names` | array of strings | List of Subject Alternative Names (SANs) for the certificate | `["www.example.com", "api.example.com"]` |
34+
| `usage_ra_tls` | boolean | Whether to include quote in the certificate for RA-TLS | `true` |
35+
| `usage_server_auth` | boolean | Enable certificate for server authentication | `true` |
36+
| `usage_client_auth` | boolean | Enable certificate for client authentication | `false` |
37+
| `random_seed` | boolean | Derive from random seed | `false` |
38+
39+
**Example:**
40+
```bash
41+
curl --unix-socket /var/run/tappd.sock -X POST \
42+
http://localhost/prpc/Tappd.DeriveKey \
43+
-H 'Content-Type: application/json' \
44+
-d '{
45+
"path": "my/key/path",
46+
"subject": "example.com",
47+
"alt_names": ["www.example.com", "api.example.com"],
48+
"usage_ra_tls": true,
49+
"usage_server_auth": true,
50+
"usage_client_auth": false,
51+
"random_seed": false
52+
}'
53+
```
54+
55+
**Response:**
56+
```json
57+
{
58+
"key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
59+
"certificate_chain": [
60+
"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
61+
"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
62+
]
63+
}
64+
```
65+
66+
### 2. Derive K256 Key
67+
68+
Derives a new ECDSA key with k256 EC curve.
69+
70+
**Endpoint:** `/prpc/Tappd.DeriveK256Key`
71+
72+
**Request Parameters:**
73+
74+
| Field | Type | Description | Example |
75+
|-------|------|-------------|----------|
76+
| `path` | string | Path to the key to derive | `"my/key/path"` |
77+
| `purpose` | string | Purpose of the key | `"signing"` |
78+
79+
**Example:**
80+
```bash
81+
curl --unix-socket /var/run/tappd.sock -X POST \
82+
http://localhost/prpc/Tappd.DeriveK256Key \
83+
-H 'Content-Type: application/json' \
84+
-d '{
85+
"path": "my/key/path",
86+
"purpose": "signing"
87+
}'
88+
```
89+
90+
**Response:**
91+
```json
92+
{
93+
"k256_key": "<hex-encoded-key>",
94+
"k256_signature_chain": [
95+
"<hex-encoded-signature-1>",
96+
"<hex-encoded-signature-2>"
97+
]
98+
}
99+
```
100+
101+
### 3. TDX Quote
102+
103+
Generates a TDX quote with report data.
104+
105+
**Endpoint:** `/prpc/Tappd.TdxQuote`
106+
107+
**Request Parameters:**
108+
109+
| Field | Type | Description | Example |
110+
|-------|------|-------------|----------|
111+
| `report_data` | string | Report data to be included in the quote | `"1234deadbeaf"` |
112+
| `hash_algorithm` | string | Hash algorithm to process the report data. Default is `sha512`. Options: `sha256`, `sha384`, `sha512`, `sha3-256`, `sha3-384`, `sha3-512`, `keccak256`, `keccak384`, `keccak512`, `raw` | `"sha512"` |
113+
| `prefix` | string | Custom prefix to prepend to report data before hashing. Defaults to 'app-data:' when hash_algorithm is not 'raw' | `"app-data:"` |
114+
115+
**Example:**
116+
```bash
117+
curl --unix-socket /var/run/tappd.sock -X POST \
118+
http://localhost/prpc/Tappd.TdxQuote \
119+
-H 'Content-Type: application/json' \
120+
-d '{
121+
"report_data": "1234deadbeaf",
122+
"hash_algorithm": "sha512",
123+
"prefix": "app-data:"
124+
}'
125+
```
126+
127+
**Response:**
128+
```json
129+
{
130+
"quote": "<hex-encoded-quote>",
131+
"event_log": "quote generation log",
132+
"hash_algorithm": "sha512",
133+
"prefix": "app-data:"
134+
}
135+
```
136+
137+
### 4. Raw Quote
138+
139+
Generates a TDX quote with raw report data. This is a low-level API that should be used with caution.
140+
141+
**Endpoint:** `/prpc/Tappd.RawQuote`
142+
143+
**Request Parameters:**
144+
145+
| Field | Type | Description | Example |
146+
|-------|------|-------------|----------|
147+
| `report_data` | string | 64 bytes of raw report data(hex encoded)| `"00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"` |
148+
149+
**Example:**
150+
```bash
151+
curl --unix-socket /var/run/tappd.sock -X POST \
152+
http://localhost/prpc/Tappd.RawQuote \
153+
-H 'Content-Type: application/json' \
154+
-d '{
155+
"report_data": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
156+
}'
157+
```
158+
159+
Or
160+
161+
```bash
162+
curl --unix-socket /var/run/tappd.sock http://localhost/prpc/Tappd.RawQuote?report_data=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
163+
```
164+
165+
**Response:**
166+
```json
167+
{
168+
"quote": "<hex-encoded-quote>",
169+
"event_log": "quote generation log"
170+
}
171+
```
172+
173+
### 5. Info
174+
175+
Retrieves worker information.
176+
177+
**Endpoint:** `/prpc/Tappd.Info`
178+
179+
**Example:**
180+
```bash
181+
curl --unix-socket /var/run/tappd.sock http://localhost/prpc/Tappd.Info
182+
```
183+
184+
**Response:**
185+
```json
186+
{
187+
"app_id": "<hex-encoded-app-id>",
188+
"instance_id": "<hex-encoded-instance-id>",
189+
"app_cert": "<certificate-string>",
190+
"tcb_info": "<tcb-info-string>",
191+
"app_name": "my-app",
192+
"public_logs": true,
193+
"public_sysinfo": true,
194+
"device_id": "<hex-encoded-device-id>",
195+
"mr_aggregated": "<hex-encoded-mr-aggregated>",
196+
"mr_image": "<hex-encoded-mr-image>",
197+
"mr_key_provider": "<hex-encoded-mr-key-provider>",
198+
"key_provider_info": "<key-provider-info-string>",
199+
"compose_hash": "<hex-encoded-compose-hash>"
200+
}
201+
```
202+
203+
## Error Responses
204+
205+
All endpoints may return the following HTTP status codes:
206+
207+
- `200 OK`: Request successful
208+
- `400 Bad Request`: Invalid request parameters
209+
- `500 Internal Server Error`: Server-side error
210+
211+
Error responses will include a JSON body with error details:
212+
```json
213+
{
214+
"error": "Error description"
215+
}
216+
```

‎sdk/curl/api.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# DStack Guest Agent RPC API Documentation
2+
3+
This document describes the REST API endpoints for the DStack Guest Agent RPC service.
4+
5+
## Base URL
6+
7+
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.
8+
9+
Make sure to map the Unix socket in your Docker Compose file:
10+
11+
```yaml
12+
services:
13+
jupyter:
14+
image: quay.io/jupyter/base-notebook
15+
volumes:
16+
- /var/run/dstack.sock:/var/run/dstack.sock
17+
```
18+
19+
## Endpoints
20+
21+
### 1. Get TLS Key
22+
23+
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.
24+
25+
**Endpoint:** `/GetTlsKey`
26+
27+
**Request Parameters:**
28+
29+
| Field | Type | Description | Example |
30+
|-------|------|-------------|----------|
31+
| `subject` | string | The subject name for the certificate | `"example.com"` |
32+
| `alt_names` | array of strings | List of Subject Alternative Names (SANs) for the certificate | `["www.example.com", "api.example.com"]` |
33+
| `usage_ra_tls` | boolean | Whether to include quote in the certificate for RA-TLS | `true` |
34+
| `usage_server_auth` | boolean | Enable certificate for server authentication | `true` |
35+
| `usage_client_auth` | boolean | Enable certificate for client authentication | `false` |
36+
37+
**Example:**
38+
```bash
39+
curl --unix-socket /var/run/dstack.sock -X POST \
40+
http://dstack/GetTlsKey \
41+
-H 'Content-Type: application/json' \
42+
-d '{
43+
"subject": "example.com",
44+
"alt_names": ["www.example.com", "api.example.com"],
45+
"usage_ra_tls": true,
46+
"usage_server_auth": true,
47+
"usage_client_auth": false
48+
}'
49+
```
50+
51+
**Response:**
52+
```json
53+
{
54+
"key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
55+
"certificate_chain": [
56+
"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
57+
"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
58+
]
59+
}
60+
```
61+
62+
### 2. Get Key
63+
64+
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.
65+
66+
**Endpoint:** `/GetKey`
67+
68+
**Request Parameters:**
69+
70+
| Field | Type | Description | Example |
71+
|-------|------|-------------|----------|
72+
| `path` | string | Path for the key | `"my/key/path"` |
73+
| `purpose` | string | Purpose for the key. Can be any string. This is used in the signature chain. | `"signing"` | `"encryption"` |
74+
75+
**Example:**
76+
```bash
77+
curl --unix-socket /var/run/dstack.sock -X POST \
78+
http://dstack/GetKey \
79+
-H 'Content-Type: application/json' \
80+
-d '{
81+
"path": "my/key/path",
82+
"purpose": "signing"
83+
}'
84+
```
85+
86+
Or
87+
88+
```bash
89+
curl --unix-socket /var/run/dstack.sock http://dstack/GetKey?path=my/key/path&purpose=signing
90+
```
91+
92+
**Response:**
93+
```json
94+
{
95+
"key": "<hex-encoded-key>",
96+
"signature_chain": [
97+
"<hex-encoded-signature-1>",
98+
"<hex-encoded-signature-2>"
99+
]
100+
}
101+
```
102+
103+
### 3. Get Quote
104+
105+
Generates a TDX quote with given plain report data.
106+
107+
**Endpoint:** `/GetQuote`
108+
109+
**Request Parameters:**
110+
111+
| Field | Type | Description | Example |
112+
|-------|------|-------------|----------|
113+
| `report_data` | string | Report data of max length 64 bytes. Padding with 0s if less than 64 bytes. | `"1234deadbeaf"` |
114+
115+
**Example:**
116+
```bash
117+
curl --unix-socket /var/run/dstack.sock -X POST \
118+
http://dstack/GetQuote \
119+
-H 'Content-Type: application/json' \
120+
-d '{
121+
"report_data": "1234deadbeaf"
122+
}'
123+
```
124+
Or
125+
```bash
126+
curl --unix-socket /var/run/dstack.sock http://dstack/GetQuote?report_data=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
127+
```
128+
129+
**Response:**
130+
```json
131+
{
132+
"quote": "<hex-encoded-quote>",
133+
"event_log": "quote generation log",
134+
"report_data": "<hex-encoded-report-data>"
135+
}
136+
```
137+
138+
### 4. Get Info
139+
140+
Retrieves worker information.
141+
142+
**Endpoint:** `/Info`
143+
144+
**Example:**
145+
```bash
146+
curl --unix-socket /var/run/dstack.sock http://dstack/Info
147+
```
148+
149+
**Response:**
150+
```json
151+
{
152+
"app_id": "<hex-encoded-app-id>",
153+
"instance_id": "<hex-encoded-instance-id>",
154+
"app_cert": "<certificate-string>",
155+
"tcb_info": "<tcb-info-string>",
156+
"app_name": "my-app",
157+
"public_logs": true,
158+
"public_sysinfo": true,
159+
"device_id": "<hex-encoded-device-id>",
160+
"mr_aggregated": "<hex-encoded-mr-aggregated>",
161+
"mr_image": "<hex-encoded-mr-image>",
162+
"mr_key_provider": "<hex-encoded-mr-key-provider>",
163+
"key_provider_info": "<key-provider-info-string>",
164+
"compose_hash": "<hex-encoded-compose-hash>"
165+
}
166+
```
167+
168+
## Error Responses
169+
170+
All endpoints may return the following HTTP status codes:
171+
172+
- `200 OK`: Request successful
173+
- `400 Bad Request`: Invalid request parameters
174+
- `500 Internal Server Error`: Server-side error
175+
176+
Error responses will include a JSON body with error details:
177+
```json
178+
{
179+
"error": "Error description"
180+
}

0 commit comments

Comments
 (0)