# SecretumVault Integration Guide

SecretumVault is a post-quantum cryptography (PQC) secure vault system integrated with
Provisioning's vault-service. It provides quantum-resistant encryption for sensitive credentials
and infrastructure secrets.

## Overview

SecretumVault combines:

- **Post-Quantum Cryptography**: Algorithms resistant to quantum computer attacks
- **Hardware Acceleration**: Optional FPGA acceleration for performance
- **Distributed Architecture**: Multi-node secure storage
- **Compliance**: FIPS 140-3 ready, NIST standards

## Architecture

### Integration Points

```text
Provisioning
    ├─ CLI (Nushell)
    │   └─ nu_plugin_secretumvault
    │
    ├─ vault-service (Rust)
    │   ├─ secretumvault backend
    │   ├─ rustyvault compatibility
    │   └─ SOPS + Age integration
    │
    └─ Control Center
        └─ Secret management UI
```

### Cryptographic Stack

```text
User Secret
    ↓
KDF (Key Derivation Function)
    ├─ Argon2id (password-based)
    └─ HKDF (key-based)
    ↓
PQC Encryption Layer
    ├─ CRYSTALS-Kyber (key encapsulation)
    ├─ Falcon (signature)
    ├─ SPHINCS+ (backup signature)
    └─ Hybrid: PQC + Classical (AES-256)
    ↓
Authenticated Encryption
    ├─ ChaCha20-Poly1305
    └─ AES-256-GCM
    ↓
Secure Storage
    ├─ Local vault
    ├─ SurrealDB
    └─ Hardware module (optional)
```

## Installation

### Install SecretumVault

```bash
# Install via provisioning
provisioning install secretumvault

# Or manual installation
cd /Users/Akasha/Development/secretumvault
cargo install --path .

# Verify installation
secretumvault --version
```

### Install Nushell Plugin

```bash
# Install plugin
provisioning install nu-plugin-secretumvault

# Reload Nushell
nu -c "plugin add nu_plugin_secretumvault"

# Verify
nu -c "secretumvault-plugin version"
```

## Configuration

### Environment Setup

```bash
# Set vault location
export SECRETUMVAULT_HOME=~/.secretumvault

# Set encryption algorithm
export SECRETUMVAULT_CIPHER=kyber-aes  # kyber-aes, falcon-aes, hybrid

# Set key derivation
export SECRETUMVAULT_KDF=argon2id      # argon2id, pbkdf2

# Enable hardware acceleration (optional)
export SECRETUMVAULT_HW_ACCEL=enabled
```

### Configuration File

```yaml
# ~/.secretumvault/config.yaml
vault:
  storage_backend: surrealdb          # local, surrealdb, redis
  encryption_cipher: kyber-aes        # kyber-aes, falcon-aes, hybrid
  key_derivation: argon2id            # argon2id, pbkdf2

  # Argon2id parameters (password strength)
  kdf:
    memory: 65536                     # KB
    iterations: 3
    parallelism: 4

  # Encryption parameters
  encryption:
    key_length: 256                   # bits
    nonce_length: 12                  # bytes
    auth_tag_length: 16               # bytes

# Database backend (if using SurrealDB)
database:
  url: "surrealdb://localhost:8000"
  namespace: "provisioning"
  database: "secrets"

# Hardware acceleration (optional)
hardware:
  use_fpga: false
  fpga_device: "/dev/fpga0"

# Backup configuration
backup:
  enabled: true
  interval: 24                        # hours
  retention: 30                       # days
  encrypt_backup: true
  backup_path: ~/.secretumvault/backups

# Access logging
audit:
  enabled: true
  log_file: ~/.secretumvault/audit.log
  log_level: info
  rotate_logs: true
  retention_days: 365

# Master key management
master_key:
  protection: none                    # none, tpm, hsm, hardware-module
  rotation_enabled: true
  rotation_interval: 90               # days
```

## Usage

### Command Line Interface

```bash
# Create master key
secretumvault init

# Add secret
secretumvault secret add \
  --name database-password \
  --value "supersecret" \
  --metadata "type=database,app=api"

# Retrieve secret
secretumvault secret get database-password

# List secrets
secretumvault secret list

# Delete secret
secretumvault secret delete database-password

# Rotate key
secretumvault key rotate

# Backup vault
secretumvault backup create --output vault-backup.enc

# Restore vault
secretumvault backup restore vault-backup.enc
```

### Nushell Integration

```nushell
# Load SecretumVault plugin
plugin add nu_plugin_secretumvault

# Add secret from Nushell
let password = "mypassword"
secretumvault-plugin store "app-secret" $password

# Retrieve secret
let db_pass = (secretumvault-plugin retrieve "database-password")

# List all secrets
secretumvault-plugin list

# Delete secret
secretumvault-plugin delete "old-secret"

# Rotate key
secretumvault-plugin rotate-key
```

### Provisioning Integration

```bash
# Configure vault-service to use SecretumVault
provisioning config set security.vault.backend secretumvault

# Enable in form prefill
provisioning setup profile --use-secretumvault

# Manage secrets via CLI
provisioning vault add \
  --name aws-access-key \
  --value "AKIAIOSFODNN7EXAMPLE" \
  --metadata "provider=aws,env=production"

# Use secret in infrastructure
provisioning ai "Create AWS resources using secret aws-access-key"
```

## Post-Quantum Cryptography

### Algorithms Supported

| Algorithm | Type | NIST Status | Performance |
| --- | --- | --- | --- |
| **CRYSTALS-Kyber** | KEM | Finalist | Fast |
| **Falcon** | Signature | Finalist | Medium |
| **SPHINCS+** | Hash-based Signature | Finalist | Slower |
| **AES-256** | Hybrid (Classical) | Standard | Very fast |
| **ChaCha20** | Stream Cipher | Alternative | Fast |

### Hybrid Mode (Recommended)

SecretumVault uses **hybrid encryption** by default:

```text
Secret Input
    ↓
Key Material: Classical (AES-256) + PQC (Kyber)
    ├─ Generate AES key
    ├─ Generate Kyber keypair
    └─ Encapsulate using Kyber
    ↓
Encrypt with both algorithms
    ├─ AES-256-GCM encryption
    └─ Kyber encapsulation (public key cryptography)
    ↓
Both keys required to decrypt
    ├─ If quantum computer breaks Kyber → AES still secure
    └─ If breakthrough in AES → Kyber still secure
    ↓
Encrypted Secret Stored
```

**Advantages**:

- Protection against quantum computers (PQC)
- Protection against classical attacks (AES-256)
- Compatible with both current and future threats
- No single point of failure

### Key Rotation Strategy

```bash
# Manual key rotation
secretumvault key rotate --algorithm kyber-aes

# Scheduled rotation (every 90 days)
secretumvault key rotate --schedule 90d

# Emergency rotation
secretumvault key rotate --emergency --force
```

## Security Features

### Authentication

```bash
# Master key authentication
secretumvault auth login

# MFA for sensitive operations
secretumvault auth mfa enable --method totp

# Biometric unlock (supported platforms)
secretumvault auth enable-biometric
```

### Access Control

```bash
# Set vault permissions
secretumvault acl set database-password \
  --read "api-service,backup-service" \
  --write "admin" \
  --delete "admin"

# View access logs
secretumvault audit log --secret database-password
```

### Audit Logging

Every operation is logged:

```bash
# View audit log
secretumvault audit log --since 24h

# Export audit log
secretumvault audit export --format json > audit.json

# Monitor real-time
secretumvault audit monitor
```

**Sample Log Entry**:

```json
{
  "timestamp": "2026-01-16T01:47:00Z",
  "operation": "secret_retrieve",
  "secret": "database-password",
  "user": "api-service",
  "status": "success",
  "ip_address": "127.0.0.1",
  "device_id": "device-123"
}
```

## Disaster Recovery

### Backup Procedures

```bash
# Create encrypted backup
secretumvault backup create \
  --output /secure/vault-backup.enc \
  --compression gzip

# Verify backup integrity
secretumvault backup verify /secure/vault-backup.enc

# Restore from backup
secretumvault backup restore \
  --input /secure/vault-backup.enc \
  --verify-checksum
```

### Recovery Key

```bash
# Generate recovery key (for emergencies)
secretumvault recovery-key generate \
  --threshold 3 \
  --shares 5

# Share recovery shards
# Share with 5 trusted people, need 3 to recover

# Recover using shards
secretumvault recovery-key restore \
  --shard1 /secure/shard1.key \
  --shard2 /secure/shard2.key \
  --shard3 /secure/shard3.key
```

## Performance

### Benchmark Results

| Operation | Time | Algorithm |
| --- | --- | --- |
| Store secret | 50-100ms | Kyber-AES |
| Retrieve secret | 30-50ms | Kyber-AES |
| Key rotation | 200-500ms | Kyber-AES |
| Backup 1000 secrets | 2-3 seconds | Kyber-AES |
| Restore from backup | 3-5 seconds | Kyber-AES |

### Hardware Acceleration

With FPGA acceleration:

| Operation | Native | FPGA | Speedup |
| --- | --- | --- | --- |
| Store secret | 75ms | 15ms | 5x |
| Key rotation | 350ms | 50ms | 7x |
| Backup 1000 | 2.5s | 0.4s | 6x |

## Troubleshooting

### Cannot Initialize Vault

```bash
# Check permissions
ls -la ~/.secretumvault

# Clear corrupted state
rm ~/.secretumvault/state.lock

# Reinitialize
secretumvault init --force
```

### Slow Performance

```bash
# Check algorithm
secretumvault config get encryption.cipher

# Switch to faster algorithm
export SECRETUMVAULT_CIPHER=kyber-aes

# Enable hardware acceleration
export SECRETUMVAULT_HW_ACCEL=enabled
```

### Master Key Lost

```bash
# Use recovery key (if available)
secretumvault recovery-key restore \
  --shard1 ... --shard2 ... --shard3 ...

# If no recovery key exists, vault is unrecoverable
# Use recent backup instead
secretumvault backup restore vault-backup.enc
```

## Compliance & Standards

### Certifications

- ✅ **NIST PQC Standards**: CRYSTALS-Kyber, Falcon, SPHINCS+
- ✅ **FIPS 140-3 Ready**: Cryptographic module certification path
- ✅ **NIST SP 800-175B**: Post-quantum cryptography guidance
- ✅ **EU Cyber Resilience Act**: PQC readiness

### Export Controls

SecretumVault is subject to cryptography export controls in some jurisdictions. Ensure compliance with local regulations.

## Related Documentation

- [Security Overview](./README.md) - Security architecture
- [Encryption Guide](./encryption.md) - Encryption strategies
- [Secrets Management](./secrets-management.md) - Secret handling
- [Vault Service](../architecture/component-architecture.md#vault-service) - Microservice architecture
- [KMS Guide](./kms-guide.md) - Key management system
