| # Architecture & Flow Diagrams | |
| This document provides visual representations of the Solana Secure Signer architecture. | |
| --- | |
| ## 🏗️ System Architecture | |
| ``` | |
| ┌───────────────────────────────────────────────────────────────────────┐ | |
| │ USER APPLICATION LAYER │ | |
| │ ┌─────────────────────────────────────────────────────────────┐ │ | |
| │ │ Your Python CLI (Coldstar SOL) │ │ | |
| │ │ • Transaction building │ │ | |
| │ │ • Network communication │ │ | |
| │ │ • User interface │ │ | |
| │ └───────────────┬────────────────────────────┬─────────────────┘ │ | |
| │ │ │ │ | |
| │ │ │ │ | |
| └──────────────────┼────────────────────────────┼───────────────────────┘ | |
| │ │ | |
| ▼ ▼ | |
| ┌───────────────────────────────────────────────────────────────────────┐ | |
| │ INTEGRATION LAYER │ | |
| │ ┌──────────────────────────┐ ┌────────────────────────────────┐ │ | |
| │ │ FFI Integration │ │ CLI Subprocess Integration │ │ | |
| │ │ (Fast, Direct) │ │ (Portable, Isolated) │ │ | |
| │ │ │ │ │ │ | |
| │ │ • ctypes bindings │ │ • subprocess.run() │ │ | |
| │ │ • Shared library │ │ • stdin/stdout JSON │ │ | |
| │ │ • Direct function calls │ │ • Process isolation │ │ | |
| │ └────────────┬─────────────┘ └────────────┬───────────────────┘ │ | |
| │ │ │ │ | |
| └───────────────┼──────────────────────────────┼───────────────────────┘ | |
| │ │ | |
| └──────────┬───────────────────┘ | |
| ▼ | |
| ┌───────────────────────────────────────────────────────────────────────┐ | |
| │ RUST SIGNING CORE │ | |
| │ ┌─────────────────────────────────────────────────────────────┐ │ | |
| │ │ Public API │ │ | |
| │ │ • sign_transaction(container, passphrase, tx) │ │ | |
| │ │ • create_encrypted_container(key, passphrase) │ │ | |
| │ └────────────┬────────────────────────────────────────────────┘ │ | |
| │ ▼ │ | |
| │ ┌─────────────────────────────────────────────────────────────┐ │ | |
| │ │ Signing Logic (signer.rs) │ │ | |
| │ │ 1. Derive decryption key (Argon2id) │ │ | |
| │ │ 2. Decrypt ciphertext (AES-256-GCM) │ │ | |
| │ │ 3. Copy to secure buffer │ │ | |
| │ │ 4. Sign with Ed25519 │ │ | |
| │ │ 5. Return signature │ │ | |
| │ └────────────┬────────────────────────────────────────────────┘ │ | |
| │ ▼ │ | |
| │ ┌─────────────────────────────────────────────────────────────┐ │ | |
| │ │ Secure Memory (secure_memory.rs) │ │ | |
| │ │ • SecureBuffer: mlock/VirtualLock │ │ | |
| │ │ • Automatic zeroization on drop │ │ | |
| │ │ • Panic-safe cleanup │ │ | |
| │ └─────────────────────────────────────────────────────────────┘ │ | |
| │ │ | |
| │ Dependencies: ed25519-dalek, aes-gcm, argon2, zeroize, region │ | |
| └───────────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 🔄 Signing Flow (Detailed) | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 1: INPUT PREPARATION │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Python Application │ | |
| │ ├─ Load encrypted container (JSON file) │ | |
| │ ├─ Get passphrase (user input, secure) │ | |
| │ └─ Prepare unsigned transaction bytes │ | |
| │ │ | |
| │ Status: ✅ No sensitive data yet │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 2: ENTER RUST SECURE ZONE │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ FFI Boundary / CLI Invocation │ | |
| │ ├─ Serialize inputs to JSON/bytes │ | |
| │ ├─ Call: sign_transaction_ffi() or subprocess │ | |
| │ └─ Enter Rust memory space │ | |
| │ │ | |
| │ Status: ✅ Encrypted data crosses boundary │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 3: KEY DERIVATION │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Argon2id Key Derivation │ | |
| │ ├─ Input: passphrase + salt from container │ | |
| │ ├─ Compute: memory-hard hash │ | |
| │ ├─ Output: 32-byte AES key │ | |
| │ └─ Zeroize: passphrase copy │ | |
| │ │ | |
| │ Status: ✅ Passphrase zeroized, no plaintext key yet │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 4: MEMORY ALLOCATION & LOCKING │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ SecureKeyBuffer::new_secret_key() │ | |
| │ ├─ Allocate: 32 bytes on heap │ | |
| │ ├─ Lock: mlock()/VirtualLock() syscall │ | |
| │ ├─ Verify: lock succeeded or return error │ | |
| │ └─ Initialize: fill with zeros │ | |
| │ │ | |
| │ Memory State: │ | |
| │ ┌────────────────────────────────────┐ │ | |
| │ │ Locked RAM (32 bytes) │ │ | |
| │ │ [0, 0, 0, ..., 0] (all zeros) │ │ | |
| │ │ Status: LOCKED, not swappable │ │ | |
| │ └────────────────────────────────────┘ │ | |
| │ │ | |
| │ Status: ✅ Secure buffer ready, no sensitive data yet │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 5: DECRYPTION │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ AES-256-GCM Decryption │ | |
| │ ├─ Input: ciphertext + nonce + derived key │ | |
| │ ├─ Decrypt: to temporary Vec<u8> │ | |
| │ ├─ Verify: authentication tag │ | |
| │ └─ Output: plaintext key (32 bytes) │ | |
| │ │ | |
| │ Temporary State: │ | |
| │ ┌────────────────────────────────────┐ │ | |
| │ │ Stack/Heap (decrypted_bytes) │ │ | |
| │ │ [k₀, k₁, k₂, ..., k₃₁] │ │ | |
| │ │ Status: PLAINTEXT KEY! ⚠️ │ │ | |
| │ └────────────────────────────────────┘ │ | |
| │ │ | |
| │ Status: ⚠️ CRITICAL - Plaintext key in temporary buffer │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 6: SECURE TRANSFER │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Copy to Locked Buffer │ | |
| │ ├─ Copy: decrypted_bytes → secure_key buffer │ | |
| │ ├─ Zeroize: decrypted_bytes (constant-time) │ | |
| │ └─ Verify: no copies remain │ | |
| │ │ | |
| │ Before: After: │ | |
| │ ┌──────────────────────┐ ┌──────────────────────┐ │ | |
| │ │ Temporary Buffer │ │ Temporary Buffer │ │ | |
| │ │ [k₀, k₁, ..., k₃₁] │ ───────> │ [0, 0, ..., 0] │ │ | |
| │ │ (plaintext key) │ │ (zeroized) │ │ | |
| │ └──────────────────────┘ └──────────────────────┘ │ | |
| │ │ | |
| │ ┌──────────────────────┐ ┌──────────────────────┐ │ | |
| │ │ Locked Buffer │ │ Locked Buffer │ │ | |
| │ │ [0, 0, ..., 0] │ ───────> │ [k₀, k₁, ..., k₃₁] │ │ | |
| │ │ (empty) │ │ (plaintext key) │ │ | |
| │ └──────────────────────┘ └──────────────────────┘ │ | |
| │ │ | |
| │ Status: ✅ Key in locked memory, temporary copy zeroized │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 7: SIGNING │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Ed25519 Signing │ | |
| │ ├─ Create: SigningKey from locked buffer (borrow, no copy) │ | |
| │ ├─ Sign: signature = signing_key.sign(transaction) │ | |
| │ ├─ Output: 64-byte signature │ | |
| │ └─ Note: SigningKey borrows, doesn't own the key │ | |
| │ │ | |
| │ Memory State: │ | |
| │ ┌────────────────────────────────────┐ │ | |
| │ │ Locked Buffer │ │ | |
| │ │ [k₀, k₁, k₂, ..., k₃₁] ◄─────── SigningKey borrows │ | |
| │ │ Status: LOCKED, being used │ │ | |
| │ └────────────────────────────────────┘ │ | |
| │ │ | |
| │ Status: ⚠️ Key still in memory, being used for signing │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 8: RESULT PREPARATION │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Build Signed Transaction │ | |
| │ ├─ Allocate: new Vec<u8> for result │ | |
| │ ├─ Append: signature (64 bytes, public data) │ | |
| │ ├─ Append: original transaction │ | |
| │ └─ Return: SignedTransaction struct │ | |
| │ │ | |
| │ Status: ✅ Public signature ready, key still in locked buffer │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 9: AUTOMATIC CLEANUP (Drop) │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ SecureKeyBuffer::drop() automatically called │ | |
| │ ├─ Trigger: secure_key goes out of scope │ | |
| │ ├─ Zeroize: data.zeroize() (constant-time) │ | |
| │ ├─ Unlock: munlock()/VirtualUnlock() │ | |
| │ └─ Extra: manual write_bytes for paranoia │ | |
| │ │ | |
| │ Before Drop: After Drop: │ | |
| │ ┌──────────────────────┐ ┌──────────────────────┐ │ | |
| │ │ Locked Buffer │ │ Unlocked Memory │ │ | |
| │ │ [k₀, k₁, ..., k₃₁] │ ───────> │ [0, 0, ..., 0] │ │ | |
| │ │ (plaintext key) │ │ (zeroized) │ │ | |
| │ │ Status: LOCKED │ │ Status: FREE │ │ | |
| │ └──────────────────────┘ └──────────────────────┘ │ | |
| │ │ | |
| │ Note: This happens even if signing panicked! │ | |
| │ │ | |
| │ Status: ✅ Key completely erased from memory │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ PHASE 10: RETURN TO PYTHON │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ FFI Boundary / CLI Output │ | |
| │ ├─ Serialize: SignedTransaction to JSON │ | |
| │ ├─ Return: to Python via FFI or stdout │ | |
| │ └─ Python receives: signature + signed transaction │ | |
| │ │ | |
| │ Data Returned to Python: │ | |
| │ • signature: [s₀, s₁, ..., s₆₃] (64 bytes, public) │ | |
| │ • signed_tx: signature + transaction (public) │ | |
| │ │ | |
| │ Status: ✅ Only public data crosses boundary │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| SECURITY SUMMARY: | |
| ═══════════════════════════════════════════════════════════════════════ | |
| • Plaintext key existed in locked memory for phases 6-8 only | |
| • Key was zeroized immediately after use (phase 9) | |
| • No copies of plaintext key exist outside locked buffer | |
| • Cleanup is guaranteed even on panic | |
| • Only public data (signature) returned to Python | |
| • Private key NEVER exposed to Python memory space | |
| ═══════════════════════════════════════════════════════════════════════ | |
| ``` | |
| --- | |
| ## 📦 Data Flow (Input → Output) | |
| ``` | |
| INPUT (Python) SECURE ZONE (Rust) OUTPUT (Python) | |
| ═══════════════ ═══════════════════ ═══════════════ | |
| ┌──────────────┐ ┌──────────────┐ | |
| │ Encrypted │ │ Signature │ | |
| │ Container │────────┐ │ (64 bytes) │ | |
| │ (JSON) │ │ │ │ | |
| └──────────────┘ │ └──────────────┘ | |
| │ ▲ | |
| ┌──────────────┐ │ ┌─────────────────────┐ │ | |
| │ Passphrase │────────┼────────>│ Rust Signing Core │────────────────┤ | |
| │ (string) │ │ │ │ │ | |
| └──────────────┘ │ │ 1. Decrypt │ ┌──────────────┐ | |
| │ │ 2. Lock memory │ │ Signed │ | |
| ┌──────────────┐ │ │ 3. Sign │ │ Transaction │ | |
| │ Unsigned TX │────────┘ │ 4. Zeroize │ │ (bytes) │ | |
| │ (bytes) │ │ 5. Return │ └──────────────┘ | |
| └──────────────┘ └─────────────────────┘ ▲ | |
| │ | |
| Private key exists │ | |
| here only! Never │ | |
| leaves this box. │ | |
| │ | |
| ┌──────────────────┐ │ | |
| │ Locked Memory │ │ | |
| │ ┌────────────┐ │ │ | |
| │ │ Private │ │ │ | |
| │ │ Key │ │ │ | |
| │ │ (32 bytes) │ │ │ | |
| │ └────────────┘ │ │ | |
| │ Auto-zeroized! │ │ | |
| └──────────────────┘ │ | |
| │ | |
| ══════════════════════════════════════════════════════════════════════════│══ | |
| FFI / CLI Boundary │ | |
| ══════════════════════════════════════════════════════════════════════════╧══ | |
| Legend: | |
| ────> Data flow | |
| ═══> Security boundary | |
| ┌───┐ Data container | |
| ``` | |
| --- | |
| ## 🔒 Memory Safety Guarantees | |
| ``` | |
| ╔═══════════════════════════════════════════════════════════════════════╗ | |
| ║ MEMORY SAFETY GUARANTEES ║ | |
| ╚═══════════════════════════════════════════════════════════════════════╝ | |
| Guarantee 1: MEMORY LOCKING | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ RAM │ | |
| │ ┌───────────────────────────────────┐ │ | |
| │ │ Locked Pages (via mlock) │ ◄── Private key here │ | |
| │ │ Cannot be swapped to disk │ │ | |
| │ └───────────────────────────────────┘ │ | |
| │ ║ │ | |
| │ ║ BLOCKED (no swap) │ | |
| │ ▼ │ | |
| │ ┌───────────────────────────────────┐ │ | |
| │ │ Disk / Swap File │ ◄── Key never reaches here │ | |
| │ │ ✘ Private key CANNOT be here │ │ | |
| │ └───────────────────────────────────┘ │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| Guarantee 2: ZEROIZATION | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ Before Drop: After Drop: │ | |
| │ ┌─────────────────┐ ┌─────────────────┐ │ | |
| │ │ [k₀, k₁, ..., k₃₁]│ │ [0, 0, ..., 0] │ │ | |
| │ │ Private key │ ────────> │ All zeros │ │ | |
| │ │ SENSITIVE! ⚠️ │ │ Safe ✅ │ │ | |
| │ └─────────────────┘ └─────────────────┘ │ | |
| │ │ | |
| │ Method: zeroize crate (constant-time, not optimized out) │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| Guarantee 3: PANIC SAFETY | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ Normal Flow: Panic Flow: │ | |
| │ ┌──────────┐ ┌──────────┐ │ | |
| │ │ Signing │ │ Signing │ │ | |
| │ │ Success │ │ PANIC! │ │ | |
| │ └────┬─────┘ └────┬─────┘ │ | |
| │ │ │ │ | |
| │ ▼ ▼ │ | |
| │ ┌──────────┐ ┌──────────┐ │ | |
| │ │ Drop │ │ Drop │ ◄── Drop ALWAYS runs │ | |
| │ │ Runs │ │ Runs │ │ | |
| │ └────┬─────┘ └────┬─────┘ │ | |
| │ │ │ │ | |
| │ ▼ ▼ │ | |
| │ ┌──────────┐ ┌──────────┐ │ | |
| │ │ Zeroized │ │ Zeroized │ ◄── Key erased in both cases │ | |
| │ └──────────┘ └──────────┘ │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| Guarantee 4: NO COPIES | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ ONLY ONE instance of plaintext key exists: │ | |
| │ │ | |
| │ ┌────────────────────────────────────────────────┐ │ | |
| │ │ SecureKeyBuffer │ │ | |
| │ │ ┌──────────────────────────────────┐ │ │ | |
| │ │ │ Private Key (32 bytes) │ ◄─────── Single instance │ | |
| │ │ │ [k₀, k₁, k₂, ..., k₃₁] │ │ │ | |
| │ │ └──────────────────────────────────┘ │ │ | |
| │ │ ▲ │ │ | |
| │ │ │ borrow (no copy) │ │ | |
| │ │ │ │ │ | |
| │ │ ┌─────────┴──────────┐ │ │ | |
| │ │ │ SigningKey │ │ │ | |
| │ │ │ (borrows data) │ │ │ | |
| │ │ └─────────────────────┘ │ │ | |
| │ └────────────────────────────────────────────────┘ │ | |
| │ │ | |
| │ All other buffers (decryption, etc.) are zeroized immediately │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| Guarantee 5: EPHEMERAL LIFECYCLE | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ Function Scope: │ | |
| │ │ | |
| │ fn sign_transaction(...) { │ | |
| │ let secure_key = SecureKeyBuffer::new(); ◄── Created │ | |
| │ // ... decrypt into secure_key ... │ | |
| │ // ... use for signing ... │ | |
| │ return signature; │ | |
| │ } ◄── secure_key dropped here, automatic cleanup │ | |
| │ │ | |
| │ Key exists ONLY during function execution │ | |
| │ No global variables, no caching, no persistence │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## 🎯 Integration Comparison | |
| ``` | |
| ╔═══════════════════════════════════════════════════════════════════════╗ | |
| ║ INTEGRATION MODE COMPARISON ║ | |
| ╚═══════════════════════════════════════════════════════════════════════╝ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ FFI Mode (libsolana_secure_signer.so/dll/dylib) │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Python ←──(ctypes)──→ Rust Library │ | |
| │ │ | |
| │ Pros: │ | |
| │ ✅ Fastest (no process overhead) │ | |
| │ ✅ Direct function calls │ | |
| │ ✅ Minimal latency (~0.1ms overhead) │ | |
| │ │ | |
| │ Cons: │ | |
| │ ⚠️ Requires compiled library for platform │ | |
| │ ⚠️ Shared memory space (less isolated) │ | |
| │ │ | |
| │ Use When: │ | |
| │ • Production deployments │ | |
| │ • High transaction throughput │ | |
| │ • Minimal latency required │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ CLI Mode (solana-signer binary) │ | |
| ├─────────────────────────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Python ──(subprocess)──→ Rust Binary ──(exit)──→ All memory freed │ | |
| │ │ | |
| │ Pros: │ | |
| │ ✅ Maximum isolation (separate process) │ | |
| │ ✅ Platform-agnostic (just needs binary) │ | |
| │ ✅ Automatic cleanup (process exit) │ | |
| │ ✅ No FFI complexity │ | |
| │ │ | |
| │ Cons: │ | |
| │ ⚠️ Slower (process startup ~10-50ms) │ | |
| │ ⚠️ IPC overhead (JSON serialization) │ | |
| │ │ | |
| │ Use When: │ | |
| │ • Development/testing │ | |
| │ • Maximum security isolation │ | |
| │ • Cross-platform portability │ | |
| │ • Occasional signing (not high frequency) │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| Performance Comparison: | |
| ┌────────────────┬──────────┬───────────┬──────────────┐ | |
| │ Operation │ FFI │ CLI │ Difference │ | |
| ├────────────────┼──────────┼───────────┼──────────────┤ | |
| │ Overhead │ ~0.1ms │ ~10-50ms │ 100-500x │ | |
| │ Throughput │ High │ Low │ - │ | |
| │ Memory Safety │ Good │ Excellent│ CLI better │ | |
| │ Portability │ Medium │ High │ CLI better │ | |
| └────────────────┴──────────┴───────────┴──────────────┘ | |
| ``` | |
| This completes the visual documentation! 🎉 | |