91eefc86fa
- Add badges, competitive comparison, and 30-sec demo to README - Add Production Status section showing OQS backend is production-ready - Mark PQC KEM/signing operations complete in roadmap - Fix GitHub URL - Create CHANGELOG.md documenting all recent changes Positions SecretumVault as first Rust vault with production PQC.
196 lines
6.1 KiB
Markdown
196 lines
6.1 KiB
Markdown
# SecretumVault Demo Scripts
|
|
|
|
Two demonstration scripts showing how to use SecretumVault:
|
|
|
|
## 📦 Scripts
|
|
|
|
### 1. `demo-server.nu` - Direct HTTP API (No Plugin)
|
|
|
|
**Tests SecretumVault server via raw HTTP endpoints**
|
|
|
|
#### Usage
|
|
|
|
```bash
|
|
# Terminal 1: Start the vault server
|
|
cd /Users/Akasha/Development/secretumvault
|
|
cargo run --bin svault --features cli,server,pqc,oqs -- -c config/svault.toml server
|
|
|
|
# Terminal 2: Run the demo
|
|
cd /Users/Akasha/Development/secretumvault/examples
|
|
nu demo-server.nu
|
|
```
|
|
|
|
#### What it demonstrates
|
|
|
|
- ✅ Health check (`GET /v1/sys/health`)
|
|
- ✅ Generate PQC key (`POST /v1/transit/pqc-keys/{key}/generate`)
|
|
- ✅ Retrieve key metadata (`GET /v1/transit/keys/{key}`)
|
|
- ✅ System status (`GET /v1/sys/status`)
|
|
- ✅ List mounted engines (`GET /v1/sys/mounts`)
|
|
- ✅ Generate derived key (`POST /v1/transit/datakeys/plaintext/generate-key`)
|
|
|
|
#### Output Example
|
|
|
|
```text
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
🔐 SecretumVault Server HTTP API Demo
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
|
|
Testing raw HTTP endpoints without plugin
|
|
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
📌 Test 1: Health Check
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
|
|
Endpoint: GET /v1/sys/health
|
|
|
|
Response:
|
|
Status: success
|
|
Sealed: false
|
|
Initialized: true
|
|
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
📌 Test 2: Generate ML-KEM-768 Key (POST)
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
|
|
Endpoint: POST /v1/transit/pqc-keys/api-demo-1737441000/generate
|
|
|
|
Response:
|
|
Status: success
|
|
✅ Key generated successfully
|
|
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
📌 Test 3: Retrieve Key Metadata (GET)
|
|
════════════════════════════════════════════════════════════════════════════════
|
|
|
|
Endpoint: GET /v1/transit/keys/api-demo-1737441000
|
|
|
|
Response:
|
|
Status: success
|
|
Name: api-demo-1737441000
|
|
Algorithm: ML-KEM-768
|
|
Current Version: 1
|
|
Created: 2026-01-21T02:00:00.000000+00:00
|
|
Public Key Size: 1184 bytes
|
|
✅ Public key available in API response
|
|
```
|
|
|
|
### 2. `demo-plugin.nu` - Nushell Plugin Demo
|
|
|
|
**Located in: `/Users/Akasha/project-provisioning/plugins/nushell-plugins/nu_plugin_secretumvault/examples/demo.nu`**
|
|
|
|
Tests SecretumVault via Nushell plugin commands
|
|
|
|
#### Usage
|
|
|
|
```bash
|
|
# Terminal 1: Start the vault server
|
|
cd /Users/Akasha/Development/secretumvault
|
|
cargo run --bin svault --features cli,server,pqc,oqs -- -c config/svault.toml server
|
|
|
|
# Terminal 2: Run the plugin demo
|
|
cd /Users/Akasha/project-provisioning/plugins/nushell-plugins
|
|
nu nu_plugin_secretumvault/examples/demo.nu
|
|
```
|
|
|
|
#### Commands tested
|
|
|
|
- ✅ `generate-pqc-key` - Generate ML-KEM-768 key
|
|
- ✅ `generate-data-key` - Generate derived key
|
|
- ✅ `kem-encapsulate` - KEM encapsulation
|
|
- ✅ `version` - Plugin version
|
|
|
|
## 🔑 Key Differences
|
|
|
|
| Aspect | Server Demo | Plugin Demo |
|
|
|--------|------------|------------|
|
|
| Protocol | Raw HTTP | Nushell commands |
|
|
| Setup | Vault server only | Vault + plugin |
|
|
| Ease of use | More control | Higher level |
|
|
| Response format | JSON | Structured records |
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# 1. Terminal 1: Start vault
|
|
cd /Users/Akasha/Development/secretumvault
|
|
cargo run --bin svault --features cli,server,pqc,oqs -- -c config/svault.toml server
|
|
|
|
# 2. Terminal 2: Run server demo
|
|
cd /Users/Akasha/Development/secretumvault/examples
|
|
nu demo-server.nu
|
|
|
|
# 3. Terminal 3: Run plugin demo
|
|
cd /Users/Akasha/project-provisioning/plugins/nushell-plugins
|
|
nu nu_plugin_secretumvault/examples/demo.nu
|
|
```
|
|
|
|
## 📝 Configuration
|
|
|
|
All demos use:
|
|
|
|
- **URL**: `http://localhost:8200`
|
|
- **Token**: `mytoken`
|
|
- **Mount**: `/transit`
|
|
|
|
These can be customized in each script.
|
|
|
|
## ✅ What's Tested
|
|
|
|
### Cryptography
|
|
|
|
- Post-Quantum: ML-KEM-768 key generation, KEM operations
|
|
- Classical: AES-256-GCM key generation
|
|
- Symmetric: Data key derivation
|
|
|
|
### API Features
|
|
|
|
- Key generation and retrieval
|
|
- System status and health
|
|
- Engine mounting and management
|
|
|
|
### Integration
|
|
|
|
- HTTP API accessibility
|
|
- Plugin command availability
|
|
- Error handling
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
### Port already in use (8200)
|
|
|
|
```bash
|
|
lsof -ti:8200 | xargs kill -9
|
|
```
|
|
|
|
### Vault won't start
|
|
|
|
Check logs:
|
|
|
|
```bash
|
|
tail -50 /tmp/vault.log
|
|
```
|
|
|
|
### Plugin not found
|
|
|
|
Ensure plugin is installed:
|
|
|
|
```bash
|
|
nu -c "plugin list" | grep secretumvault
|
|
```
|
|
|
|
### String interpolation errors in Nushell
|
|
|
|
Remember to escape parentheses in `$"..."` strings:
|
|
|
|
```nushell
|
|
print $"Size: {$size} bytes \(standard\)" # ✅ Correct
|
|
print $"Size: {$size} bytes (standard)" # ❌ Wrong - parsing error
|
|
```
|
|
|
|
## 📚 Further Reading
|
|
|
|
- Vault docs: See `svault --help`
|
|
- Plugin docs: See `secretumvault --help`
|
|
- API reference: Check endpoint responses
|