qssh 0.0.2-alpha

# KIRQ Integration Guide for QSSH + PQ-QKD-Proxy

## Overview
This guide explains how to integrate QSSH with QKD hardware through the PQ-QKD-Proxy. All code is already complete and tested - this is purely deployment and configuration.

## Current Status

### ✅ Already Completed on QSSH Side
1. **QKD Client Implementation** (`/src/qkd/mod.rs`)
   - BB84 and E91 protocol support
   - Proof generation and verification
   - Key combination with PQC

2. **Server-Side QKD Support** (`/src/handshake.rs`)
   - Servers can verify QKD proofs
   - Combine QKD keys with PQC keys using XOR
   - Full bidirectional QKD support

3. **Key Rotation with QKD** (`/src/key_rotation.rs`)
   - Automatic key rotation at intervals
   - QKD integration for rotation keys
   - Statistics tracking

4. **Post-Quantum Crypto** (`/src/crypto/falcon_safe.rs`)
   - Falcon-512 for key exchange
   - SPHINCS+ for signatures
   - Safe implementation for macOS and Linux

### ✅ Already Completed in PQ-QKD-Proxy
Repository: https://github.com/QuantumVerseProtocols/pq-qkd-proxy

- Post-quantum secure proxy for vendor APIs
- Falcon-512 + SPHINCS+ (same as QSSH)
- Localhost-only access to vendor TLS
- Audit logging and key rotation

## KIRQ Deployment Steps

### Step 1: Install PQ-QKD-Proxy on QKD Hardware

```bash
# SSH into your QKD hardware (Toshiba/IDQuantique)
ssh kirq@qkd-hardware

# Clone and build the proxy
git clone https://github.com/QuantumVerseProtocols/pq-qkd-proxy
cd pq-qkd-proxy
cargo build --release

# Install system-wide
sudo ./install.sh
```

### Step 2: Configure the Proxy

Edit `/etc/pq-qkd-proxy/config.toml`:

```toml
[proxy]
# External interface for QSSH clients
listen = "0.0.0.0:8443"  # Or specific IP

[qkd]
# Vendor API - MUST be localhost only
vendor_api = "https://localhost:443"
vendor_type = "toshiba"  # or "idquantique"
vendor_cert = "/etc/qkd/vendor-cert.pem"

[security]
# Must match QSSH settings
pq_algorithm = "falcon512"
sig_algorithm = "sphincsplus"
key_rotation_interval = 3600

# Path to authorized QSSH client keys
authorized_keys = "/etc/pq-qkd-proxy/authorized_keys"
audit_log = "/var/log/pq-qkd-proxy/audit.log"
```

### Step 3: Generate Proxy Keys

```bash
# Generate the proxy's Falcon/SPHINCS+ keys
cd /etc/pq-qkd-proxy
pq-qkd-proxy --generate-keys

# This creates:
# - proxy_falcon.key / proxy_falcon.pub
# - proxy_sphincs.key / proxy_sphincs.pub
```

### Step 4: Add QSSH Client Keys

```bash
# Copy QSSH client's public keys to authorized_keys
echo "client_id=qssh1 falcon_pubkey=<base64> sphincs_pubkey=<base64>" >> /etc/pq-qkd-proxy/authorized_keys
```

### Step 5: Configure Firewall

```bash
# Block direct access to vendor API
sudo iptables -A INPUT -p tcp --dport 443 -s 127.0.0.1 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j DROP

# Allow proxy port
sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
```

### Step 6: Start the Proxy Service

```bash
# Start and enable the service
sudo systemctl start pq-qkd-proxy
sudo systemctl enable pq-qkd-proxy

# Check status
sudo systemctl status pq-qkd-proxy
sudo journalctl -u pq-qkd-proxy -f
```

## QSSH Client Configuration

### Update QSSH Config
In your QSSH client configuration:

```rust
// OLD - Direct to QKD hardware (INSECURE)
// qkd_endpoint: "https://qkd-hardware.local:443"

// NEW - Through PQ proxy (QUANTUM-SAFE)
qkd_endpoint: "https://qkd-proxy.example.com:8443"
```

### Test the Connection

```bash
# From QSSH client machine
cd /Users/sylvaincormier/qssh

# Test QKD connection through proxy
cargo run --features qkd -- --qkd-test qkd-proxy.example.com:8443

# Run QSSH with QKD enabled
cargo run --features qkd -- -Q user@server
```

## Architecture Diagram

```
┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│ QSSH Client │◄────────►│ PQ-QKD-Proxy │◄────────►│ QKD Hardware│
└─────────────┘         └──────────────┘         └─────────────┘
     │                         │                        │
     │ Falcon-512             │                        │
     │ SPHINCS+               │ Runs on same          │ Vendor
     │ Quantum-Safe           │ machine as QKD        │ TLS API
     │                        │                        │ (Hidden)
     │                        │                        │
     └────────────────────────┘                        │
          External Network     │     Localhost Only    │
                              └────────────────────────┘
```

## Verification Checklist

- [ ] PQ-QKD-Proxy installed on QKD hardware
- [ ] Proxy configured with correct vendor API endpoint
- [ ] Falcon/SPHINCS+ keys generated for proxy
- [ ] QSSH client authorized in proxy config
- [ ] Firewall blocking direct vendor API access
- [ ] Proxy service running and accessible
- [ ] QSSH client configured to use proxy endpoint
- [ ] Test connection successful
- [ ] Audit logs showing key requests

## Troubleshooting

### Connection Refused
```bash
# Check proxy is listening
sudo netstat -tlnp | grep 8443

# Check firewall rules
sudo iptables -L -n
```

### Authentication Failed
```bash
# Check authorized_keys
cat /etc/pq-qkd-proxy/authorized_keys

# Check client has matching keys
cat ~/.qssh/falcon.pub
```

### Vendor API Errors
```bash
# Test localhost connectivity
curl -k https://localhost:443/api/status

# Check vendor service
systemctl status qkd-vendor-api
```

### View Audit Logs
```bash
sudo tail -f /var/log/pq-qkd-proxy/audit.log
```

## Security Notes

1. **NEVER expose vendor TLS API to network** - Only localhost access
2. **Always use proxy for external access** - Ensures quantum-safe communication
3. **Rotate keys regularly** - Both proxy and client keys
4. **Monitor audit logs** - Track all key requests
5. **Keep proxy updated** - Security patches and improvements

## Integration Testing

Once deployed, test the full chain:

```bash
# 1. Test proxy health
curl https://qkd-proxy.example.com:8443/health

# 2. Test QSSH QKD negotiation
cargo test --features qkd test_qkd_integration

# 3. Verify key generation
cargo run --features qkd -- --qkd-verify

# 4. Check security monitoring
cargo run --bin qssh-monitor
# Open http://localhost:8080/security-monitor.html
```

## Support

- QSSH Issues: https://github.com/QuantumVerseProtocols/qssh/issues
- PQ-QKD-Proxy Issues: https://github.com/QuantumVerseProtocols/pq-qkd-proxy/issues

## Summary

**All code is complete.** This is purely deployment:

1. Install `pq-qkd-proxy` on QKD hardware
2. Configure it to talk to vendor API on localhost
3. Point QSSH clients to proxy instead of vendor API
4. Everything else works automatically

The proxy provides the quantum-safe bridge between QSSH and the vulnerable vendor APIs, ensuring end-to-end post-quantum security.