# SSH Temporal Keys - User Guide\n\n## Quick Start\n\n### Generate and Connect with Temporary Key\n\nThe fastest way to use temporal SSH keys:\n\n```\n# Auto-generate, deploy, and connect (key auto-revoked after disconnect)\nssh connect server.example.com\n\n# Connect with custom user and TTL\nssh connect server.example.com --user deploy --ttl 30 min\n\n# Keep key active after disconnect\nssh connect server.example.com --keep\n```\n\n### Manual Key Management\n\nFor more control over the key lifecycle:\n\n```\n# 1. Generate key\nssh generate-key server.example.com --user root --ttl 1hr\n\n# Output:\n# ✓ SSH key generated successfully\n#   Key ID: abc-123-def-456\n#   Type: dynamickeypair\n#   User: root\n#   Server: server.example.com\n#   Expires: 2024-01-01T13:00:00Z\n#   Fingerprint: SHA256:...\n#\n# Private Key (save securely):\n# -----BEGIN OPENSSH PRIVATE KEY-----\n# ...\n# -----END OPENSSH PRIVATE KEY-----\n\n# 2. Deploy key to server\nssh deploy-key abc-123-def-456\n\n# 3. Use the private key to connect\nssh -i /path/to/private/key root@server.example.com\n\n# 4. Revoke when done\nssh revoke-key abc-123-def-456\n```\n\n## Key Features\n\n### Automatic Expiration\n\nAll keys expire automatically after their TTL:\n\n- **Default TTL**: 1 hour\n- **Configurable**: From 5 minutes to 24 hours\n- **Background Cleanup**: Automatic removal from servers every 5 minutes\n\n### Multiple Key Types\n\nChoose the right key type for your use case:\n\n| Type | Description | Use Case |\n| ------ | ------------- | ---------- |\n| **dynamic** (default) | Generated Ed25519 keys | Quick SSH access |\n| **ca** | Vault CA-signed certificate | Enterprise with SSH CA |\n| **otp** | Vault one-time password | Single-use access |\n\n### Security Benefits\n\n✅ No static SSH keys to manage\n✅ Short-lived credentials (1 hour default)\n✅ Automatic cleanup on expiration\n✅ Audit trail for all operations\n✅ Private keys never stored on disk\n\n## Common Usage Patterns\n\n### Development Workflow\n\n```\n# Quick SSH for debugging\nssh connect dev-server.local --ttl 30 min\n\n# Execute commands\nssh root@dev-server.local "systemctl status nginx"\n\n# Connection closes, key auto-revokes\n```\n\n### Production Deployment\n\n```\n# Generate key with longer TTL for deployment\nssh generate-key prod-server.example.com --ttl 2hr\n\n# Deploy to server\nssh deploy-key <key-id>\n\n# Run deployment script\nssh -i /tmp/deploy-key root@prod-server.example.com < deploy.sh\n\n# Manual revoke when done\nssh revoke-key <key-id>\n```\n\n### Multi-Server Access\n\n```\n# Generate one key\nssh generate-key server01.example.com --ttl 1hr\n\n# Use the same private key for multiple servers (if you have provisioning access)\n# Note: Currently each key is server-specific, multi-server support coming soon\n```\n\n## Command Reference\n\n### ssh generate-key\n\nGenerate a new temporal SSH key.\n\n**Syntax**:\n\n```\nssh generate-key <server> [options]\n```\n\n**Options**:\n\n- `--user <name>`: SSH user (default: root)\n- `--ttl <duration>`: Key lifetime (default: 1hr)\n- `--type <ca|otp|dynamic>`: Key type (default: dynamic)\n- `--ip <address>`: Allowed IP (OTP mode only)\n- `--principal <name>`: Principal (CA mode only)\n\n**Examples**:\n\n```\n# Basic usage\nssh generate-key server.example.com\n\n# Custom user and TTL\nssh generate-key server.example.com --user deploy --ttl 30 min\n\n# Vault CA mode\nssh generate-key server.example.com --type ca --principal admin\n```\n\n### ssh deploy-key\n\nDeploy a generated key to the target server.\n\n**Syntax**:\n\n```\nssh deploy-key <key-id>\n```\n\n**Example**:\n\n```\nssh deploy-key abc-123-def-456\n```\n\n### ssh list-keys\n\nList all active SSH keys.\n\n**Syntax**:\n\n```\nssh list-keys [--expired]\n```\n\n**Examples**:\n\n```\n# List active keys\nssh list-keys\n\n# Show only deployed keys\nssh list-keys | where deployed == true\n\n# Include expired keys\nssh list-keys --expired\n```\n\n### ssh get-key\n\nGet detailed information about a specific key.\n\n**Syntax**:\n\n```\nssh get-key <key-id>\n```\n\n**Example**:\n\n```\nssh get-key abc-123-def-456\n```\n\n### ssh revoke-key\n\nImmediately revoke a key (removes from server and tracking).\n\n**Syntax**:\n\n```\nssh revoke-key <key-id>\n```\n\n**Example**:\n\n```\nssh revoke-key abc-123-def-456\n```\n\n### ssh connect\n\nAuto-generate, deploy, connect, and revoke (all-in-one).\n\n**Syntax**:\n\n```\nssh connect <server> [options]\n```\n\n**Options**:\n\n- `--user <name>`: SSH user (default: root)\n- `--ttl <duration>`: Key lifetime (default: 1hr)\n- `--type <ca|otp|dynamic>`: Key type (default: dynamic)\n- `--keep`: Don't revoke after disconnect\n\n**Examples**:\n\n```\n# Quick connection\nssh connect server.example.com\n\n# Custom user\nssh connect server.example.com --user deploy\n\n# Keep key active after disconnect\nssh connect server.example.com --keep\n```\n\n### ssh stats\n\nShow SSH key statistics.\n\n**Syntax**:\n\n```\nssh stats\n```\n\n**Example Output**:\n\n```\nSSH Key Statistics:\n  Total generated: 42\n  Active keys: 10\n  Expired keys: 32\n\nKeys by type:\n  dynamic: 35\n  otp: 5\n  certificate: 2\n\nLast cleanup: 2024-01-01T12:00:00Z\n  Cleaned keys: 5\n```\n\n### ssh cleanup\n\nManually trigger cleanup of expired keys.\n\n**Syntax**:\n\n```\nssh cleanup\n```\n\n### ssh test\n\nRun a quick test of the SSH key system.\n\n**Syntax**:\n\n```\nssh test <server> [--user <name>]\n```\n\n**Example**:\n\n```\nssh test server.example.com --user root\n```\n\n### ssh help\n\nShow help information.\n\n**Syntax**:\n\n```\nssh help\n```\n\n## Duration Formats\n\nThe `--ttl` option accepts various duration formats:\n\n| Format | Example | Meaning |\n| -------- | --------- | --------- |\n| Minutes | `30 min` | 30 minutes |\n| Hours | `2hr` | 2 hours |\n| Mixed | `1hr 30 min` | 1.5 hours |\n| Seconds | `3600sec` | 1 hour |\n\n## Working with Private Keys\n\n### Saving Private Keys\n\nWhen you generate a key, save the private key immediately:\n\n```\n# Generate and save to file\nssh generate-key server.example.com | get private_key | save -f ~/.ssh/temp_key\nchmod 600 ~/.ssh/temp_key\n\n# Use the key\nssh -i ~/.ssh/temp_key root@server.example.com\n\n# Cleanup\nrm ~/.ssh/temp_key\n```\n\n### Using SSH Agent\n\nAdd the temporary key to your SSH agent:\n\n```\n# Generate key and extract private key\nssh generate-key server.example.com | get private_key | save -f /tmp/temp_key\nchmod 600 /tmp/temp_key\n\n# Add to agent\nssh-add /tmp/temp_key\n\n# Connect (agent provides the key automatically)\nssh root@server.example.com\n\n# Remove from agent\nssh-add -d /tmp/temp_key\nrm /tmp/temp_key\n```\n\n## Troubleshooting\n\n### Key Deployment Fails\n\n**Problem**: `ssh deploy-key` returns error\n\n**Solutions**:\n\n1. Check SSH connectivity to server:\n\n   ```bash\n   ssh root@server.example.com\n   ```\n\n1. Verify provisioning key is configured:\n\n   ```bash\n   echo $PROVISIONING_SSH_KEY\n   ```\n\n2. Check server SSH daemon:\n\n   ```bash\n   ssh root@server.example.com "systemctl status sshd"\n   ```\n\n### Private Key Not Working\n\n**Problem**: SSH connection fails with "Permission denied (publickey)"\n\n**Solutions**:\n\n1. Verify key was deployed:\n\n   ```bash\n   ssh list-keys | where id == "<key-id>"\n   ```\n\n2. Check key hasn't expired:\n\n   ```bash\n   ssh get-key <key-id> | get expires_at\n   ```\n\n3. Verify private key permissions:\n\n   ```bash\n   chmod 600 /path/to/private/key\n   ```\n\n### Cleanup Not Running\n\n**Problem**: Expired keys not being removed\n\n**Solutions**:\n\n1. Check orchestrator is running:\n\n   ```bash\n   curl http://localhost:9090/health\n   ```\n\n2. Trigger manual cleanup:\n\n   ```bash\n   ssh cleanup\n   ```\n\n3. Check orchestrator logs:\n\n   ```bash\n   tail -f ./data/orchestrator.log | grep SSH\n   ```\n\n## Best Practices\n\n### Security\n\n1. **Short TTLs**: Use the shortest TTL that works for your task\n\n   ```bash\n   ssh connect server.example.com --ttl 30 min\n   ```\n\n2. **Immediate Revocation**: Revoke keys when you're done\n\n   ```bash\n   ssh revoke-key <key-id>\n   ```\n\n3. **Private Key Handling**: Never share or commit private keys\n\n   ```bash\n   # Save to temp location, delete after use\n   ssh generate-key server.example.com | get private_key | save -f /tmp/key\n   # ... use key ...\n   rm /tmp/key\n   ```\n\n### Workflow Integration\n\n1. **Automated Deployments**: Generate key in CI/CD\n\n   ```bash\n   #!/bin/bash\n   KEY_ID=$(ssh generate-key prod.example.com --ttl 1hr | get id)\n   ssh deploy-key $KEY_ID\n   # Run deployment\n   ansible-playbook deploy.yml\n   ssh revoke-key $KEY_ID\n   ```\n\n2. **Interactive Use**: Use `ssh connect` for quick access\n\n   ```bash\n   ssh connect dev.example.com\n   ```\n\n3. **Monitoring**: Check statistics regularly\n\n   ```bash\n   ssh stats\n   ```\n\n## Advanced Usage\n\n### Vault Integration\n\nIf your organization uses HashiCorp Vault:\n\n#### CA Mode (Recommended)\n\n```\n# Generate CA-signed certificate\nssh generate-key server.example.com --type ca --principal admin --ttl 1hr\n\n# Vault signs your public key\n# Server must trust Vault CA certificate\n```\n\n**Setup** (one-time):\n\n```\n# On servers, add to /etc/ssh/sshd_config:\nTrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem\n\n# Get Vault CA public key:\nvault read -field=public_key ssh/config/ca | \\n  sudo tee /etc/ssh/trusted-user-ca-keys.pem\n\n# Restart SSH:\nsudo systemctl restart sshd\n```\n\n#### OTP Mode\n\n```\n# Generate one-time password\nssh generate-key server.example.com --type otp --ip 192.168.1.100\n\n# Use the OTP to connect (single use only)\n```\n\n### Scripting\n\nUse in scripts for automated operations:\n\n```\n# deploy.nu\ndef deploy [target: string] {\n    let key = (ssh generate-key $target --ttl 1hr)\n    ssh deploy-key $key.id\n\n    # Run deployment\n    try {\n        ssh $"root@($target)" "bash /path/to/deploy.sh"\n    } catch {\n        print "Deployment failed"\n    }\n\n    # Always cleanup\n    ssh revoke-key $key.id\n}\n```\n\n## API Integration\n\nFor programmatic access, use the REST API:\n\n```\n# Generate key\ncurl -X POST http://localhost:9090/api/v1/ssh/generate \\n  -H "Content-Type: application/json" \\n  -d '{\n    "key_type": "dynamickeypair",\n    "user": "root",\n    "target_server": "server.example.com",\n    "ttl_seconds": 3600\n  }'\n\n# Deploy key\ncurl -X POST http://localhost:9090/api/v1/ssh/{key_id}/deploy\n\n# List keys\ncurl http://localhost:9090/api/v1/ssh/keys\n\n# Get stats\ncurl http://localhost:9090/api/v1/ssh/stats\n```\n\n## FAQ\n\n**Q: Can I use the same key for multiple servers?**\nA: Currently, each key is tied to a specific server. Multi-server support is planned.\n\n**Q: What happens if the orchestrator crashes?**\nA: Keys in memory are lost, but keys already deployed to servers remain until their expiration time.\n\n**Q: Can I extend the TTL of an existing key?**\nA: No, you must generate a new key. This is by design for security.\n\n**Q: What's the maximum TTL?**\nA: Configurable by admin, default maximum is 24 hours.\n\n**Q: Are private keys stored anywhere?**\nA: Private keys exist only in memory during generation and are shown once to the user. They are never written to disk by the system.\n\n**Q: What happens if cleanup fails?**\nA: The key remains in authorized_keys until the next cleanup run. You can trigger manual cleanup with `ssh cleanup`.\n\n**Q: Can I use this with non-root users?**\nA: Yes, use `--user <username>` when generating the key.\n\n**Q: How do I know when my key will expire?**\nA: Use `ssh get-key <key-id>` to see the exact expiration timestamp.\n\n## Support\n\nFor issues or questions:\n\n1. Check orchestrator logs: `tail -f ./data/orchestrator.log`\n2. Run diagnostics: `ssh stats`\n3. Test connectivity: `ssh test server.example.com`\n4. Review documentation: `SSH_KEY_MANAGEMENT.md`\n\n## See Also\n\n- **Architecture**: `SSH_KEY_MANAGEMENT.md`\n- **Implementation**: `SSH_IMPLEMENTATION_SUMMARY.md`\n- **Configuration**: `config/ssh-config.toml.example`
