Last updated
┌─────────────────────────────────────────────────────────────────────────────┐
│ NITRO ENCLAVE │
│ (Isolated VM Instance) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ VSOCK Server (Port 5000) │ │
│ │ src/vsock-server.ts │ │
│ └────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Handler Router │ │
│ │ src/handlers/index.ts │ │
│ └────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Health │ │ Key Gen │ │ Rust │ │
│ │ Handler │ │ Handler │ │ Handler │ │
│ │ health.ts │ │ keygen.ts │ │ rust.ts │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ In-Memory Session Storage │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ pendingDKGs │ │ enclaveSessions │ │ walletSessions │ │ │
│ │ │ Map<string, │ │ Map<string, │ │ Map<string, │ │ │
│ │ │ PendingDKG> │ │ EnclaveSession>│ │ WalletSession> │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Cryptographic Operations │ │
│ │ • ECDH Key Exchange (prime256v1) │ │
│ │ • AES-256-GCM Encryption/Decryption │ │
│ │ • ECDSA Partial Signing (secp256k1) │ │
│ │ • EC Point Addition for Public Key │ │
│ │ • Lagrange Interpolation │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ NSM Attestation (Rust) │ │
│ │ /app/bin/hello_rust │ │
│ │ • Generate attestation document │ │
│ │ • Communicate with Nitro Security Module │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘// parent-client.js
const VSOCK_PORT = 5000; // Must match enclave
const PARENT_CID = 3; // Parent instance always uses CID 3
// Enclave CID is dynamically discovered:
// nitro-cli describe-enclaves → JSON[0].EnclaveCID┌─────────────────────────────────────────────────────────────────────────────┐
│ VSOCK CONNECTION LIFECYCLE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PARENT INSTANCE NITRO ENCLAVE │
│ (parent-client.js) (vsock-server.ts) │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 1. Create Socket │ │ Listening on │ │
│ │ VsockSocket() │ │ Port 5000 │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ │ 2. Connect to Enclave CID:PORT │ │
│ │ client.connect(cid, 5000) │ │
│ ├────────────────────────────────────────────▶ │
│ │ │ │
│ │ 3. Accept Connection │ │
│ │ onConnection() │ │
│ ◀────────────────────────────────────────────┤ │
│ │ │ │
│ ┌──────────┴──────────┐ ┌──────────┴──────────┐ │
│ │ 4. Send Request │ │ 5. Receive Data │ │
│ │ writeTextSync() │──────JSON Request───▶│ onData() │ │
│ │ {type, data} │ │ Buffer accumulate│ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ │ ┌──────────┴──────────┐ │
│ │ │ 6. Parse & Process │ │
│ │ │ JSON.parse() │ │
│ │ │ processRequest() │ │
│ │ │ Route to handler │ │
│ │ └──────────┬──────────┘ │
│ │ │ │
│ ┌──────────┴──────────┐ ┌──────────┴──────────┐ │
│ │ 8. Receive Response │ │ 7. Send Response │ │
│ │ onData() │◀─────JSON Response───│ writeTextSync() │ │
│ │ Parse JSON │ + newline │ {success, data} │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ ┌──────────┴──────────┐ ┌──────────┴──────────┐ │
│ │ 9. Close Connection │ │ 10. Close Socket │ │
│ │ client.end() │ │ setTimeout 10ms │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘// src/types/vsock.types.ts
interface VsockRequest {
type: RequestType; // Handler identifier (e.g., 'dkgInit', 'partialSign')
data?: any; // Request-specific payload
}
interface VsockResponse {
success: boolean; // Operation success status
data?: any; // Response payload
error?: string; // Error message if failed
timestamp: string; // ISO timestamp
}// parent-client.js - sendToEnclave()
async function sendToEnclave(request) {
return new Promise((resolve, reject) => {
const cid = getEnclaveCID(); // Dynamic CID discovery
const client = new VsockSocket();
let responseData = '';
const timeout = setTimeout(() => {
client.end();
reject(new Error('Request timeout'));
}, 30000); // 30 second timeout
client.on('data', (buf) => {
responseData += buf.toString();
if (responseData.includes('\n')) {
const response = JSON.parse(responseData.trim());
clearTimeout(timeout);
client.end();
resolve(response);
}
});
client.connect(cid, VSOCK_PORT, () => {
client.writeTextSync(JSON.stringify(request));
});
});
}// src/vsock-server.ts
class EnclaveVsockServer {
constructor(port: number = 5000) {
this.server = new VsockServer();
this.server.on('connection', (socket: VsockSocket) => {
let dataBuffer = '';
socket.on('data', async (data: Buffer) => {
dataBuffer += data.toString();
// Prevent buffer overflow
if (dataBuffer.length > 10240) {
dataBuffer = '';
return;
}
try {
const request = JSON.parse(dataBuffer);
const response = await this.processRequest(request);
socket.writeTextSync(JSON.stringify(response) + '\n');
setTimeout(() => socket.close(), 10);
} catch (e) {
// Not valid JSON yet, wait for more data
}
});
});
this.server.listen(port);
}
}┌─────────────────────────────────────────────────────────────────────────────┐
│ 3-PARTY SHARE DISTRIBUTION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SHARE 1 (Client) SHARE 2 (Active) SHARE 3 (Backup) │
│ ═══════════════ ════════════════ ════════════════ │
│ │
│ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Browser │ │ Nitro Enclave │ │ Nitro Enclave │ │
│ │ (Local) │ │ (Encrypted in │ │ (Encrypted in │ │
│ │ │ │ S3 + KMS) │ │ S3 + KMS) │ │
│ └─────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ • Stored in browser • Stored encrypted in • Stored encrypted │
│ localStorage AWS S3 in AWS S3 │
│ • Never leaves device • Decrypted only in • For recovery only │
│ • Required for signing enclave • 2-of-3 threshold │
│ • Required for signing │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SIGNING REQUIRES: Share 1 (Client) + Share 2 (Enclave) │
│ RECOVERY USES: Share 1 (Client) + Share 3 (Enclave) OR │
│ Share 2 (Enclave) + Share 3 (Enclave) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ ENCRYPTION LAYERS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: ECDH Key Exchange (Browser ↔ Enclave) │
│ ═════════════════════════════════════════════ │
│ • Curve: prime256v1 (P-256) │
│ • Purpose: Encrypt sensitive share contributions during DKG │
│ • Protection: Man-in-the-middle during DKG handshake │
│ │
│ Layer 2: AES-256-GCM (Share Storage) │
│ ════════════════════════════════════ │
│ • Algorithm: AES-256-GCM (authenticated encryption) │
│ • Key Source: AWS KMS GenerateDataKey │
│ • Purpose: Encrypt shares before S3 storage │
│ • Protection: Shares at rest in S3 │
│ │
│ Layer 3: AWS KMS (Key Management) │
│ ════════════════════════════════ │
│ • Purpose: Generate and manage data encryption keys │
│ • Key ID: 33b03d30-4e5d-4460-a971-91c975b7b82f │
│ • Protection: Data keys never stored in plaintext │
│ │
│ Layer 4: Nitro Enclave (Hardware Isolation) │
│ ═══════════════════════════════════════════ │
│ • Purpose: Isolated execution environment │
│ • Protection: Memory isolation, no persistent storage, attestation │
│ • Communication: vsock only (no network access) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────────────┐
│ WHAT EACH PARTY CAN ACCESS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ BROWSER (Client) │
│ ├── ✅ Share 1 (plaintext) │
│ ├── ✅ Public key │
│ ├── ✅ Ethereum address │
│ ├── ✅ Session ID │
│ └── ❌ Share 2, Share 3 │
│ │
│ PARENT INSTANCE (Relay) │
│ ├── ✅ Encrypted shares (ciphertext only) │
│ ├── ✅ Encrypted KMS data keys │
│ ├── ✅ Public key, Ethereum address │
│ ├── ✅ Session metadata │
│ └── ❌ Plaintext shares, plaintext data keys │
│ │
│ NITRO ENCLAVE │
│ ├── ✅ All shares (temporarily, in memory) │
│ ├── ✅ Plaintext data keys (temporarily) │
│ ├── ✅ All cryptographic operations │
│ └── ❌ Network access, persistent storage │
│ │
│ AWS S3 │
│ ├── ✅ Encrypted Share 2 │
│ ├── ✅ Encrypted Share 3 │
│ ├── ✅ Encrypted KMS data key │
│ └── ❌ Any plaintext cryptographic material │
│ │
└─────────────────────────────────────────────────────────────────────────────┘