# Vault TLS Configuration Guide

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

## Overview

This guide explains how to configure TLS for the Phoenix Vault cluster. TLS can be configured using:
- Let's Encrypt (recommended for production)
- Custom certificates
- Self-signed certificates (development only)

## TLS Directory Structure

TLS certificates are stored in `/opt/vault/tls/` on each node:
- `vault.crt` - Certificate file
- `vault.key` - Private key file
- `ca.crt` - CA certificate (if using custom CA)

## Let's Encrypt Setup (Recommended)

### Prerequisites
- Domain name pointing to Vault nodes (or use DNS challenge)
- Certbot installed on a management node
- Port 80 or 443 accessible for ACME challenge

### Steps

1. **Install Certbot** (on management node):
```bash
apt-get update
apt-get install -y certbot
```

2. **Obtain Certificates**:
```bash
# For each Vault node
certbot certonly --standalone -d vault-phoenix-1.example.com
certbot certonly --standalone -d vault-phoenix-2.example.com
certbot certonly --standalone -d vault-phoenix-3.example.com
```

3. **Copy Certificates to Vault Nodes**:
```bash
# Node 1
scp /etc/letsencrypt/live/vault-phoenix-1.example.com/fullchain.pem root@192.168.11.11:/tmp/vault.crt
scp /etc/letsencrypt/live/vault-phoenix-1.example.com/privkey.pem root@192.168.11.11:/tmp/vault.key
ssh root@192.168.11.11 "pct push 8640 /tmp/vault.crt /opt/vault/tls/vault.crt && pct push 8640 /tmp/vault.key /opt/vault/tls/vault.key && pct exec 8640 -- chown vault:vault /opt/vault/tls/* && pct exec 8640 -- chmod 600 /opt/vault/tls/vault.key && pct exec 8640 -- chmod 644 /opt/vault/tls/vault.crt"

# Repeat for nodes 2 and 3
```

4. **Update Vault Configuration**:
Update `/etc/vault.d/vault.hcl` on each node:
```hcl
listener "tcp" {
  address          = "0.0.0.0:8200"
  cluster_address  = "10.160.0.40:8201"
  tls_cert_file    = "/opt/vault/tls/vault.crt"
  tls_key_file     = "/opt/vault/tls/vault.key"
  tls_min_version  = "1.2"
  tls_cipher_suites = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
}
```

5. **Restart Vault Services**:
```bash
ssh root@192.168.11.11 "pct exec 8640 -- systemctl restart vault"
ssh root@192.168.11.12 "pct exec 8641 -- systemctl restart vault"
ssh root@192.168.11.11 "pct exec 8642 -- systemctl restart vault"
```

6. **Set Up Auto-Renewal**:
```bash
# Add to crontab on management node
0 2 * * * certbot renew --quiet --deploy-hook "/path/to/renew-vault-certs.sh"
```

## Custom Certificates

1. **Generate Certificate Signing Request (CSR)**:
```bash
openssl genrsa -out vault.key 2048
openssl req -new -key vault.key -out vault.csr
```

2. **Sign Certificate with CA**:
```bash
openssl x509 -req -in vault.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out vault.crt -days 365
```

3. **Copy to Vault Nodes** (same as Let's Encrypt step 3)

4. **Update Configuration** (same as Let's Encrypt step 4)

## Self-Signed Certificates (Development Only)

```bash
# Generate self-signed certificate
openssl req -x509 -newkey rsa:2048 -keyout vault.key -out vault.crt -days 365 -nodes \
  -subj "/CN=vault-phoenix-1/O=Sankofa/C=US"

# Copy to all nodes
# Update configuration
```

## Verification

After enabling TLS:
```bash
# Test HTTPS connection
curl -k https://10.160.0.40:8200/v1/sys/health

# Check certificate
openssl s_client -connect 10.160.0.40:8200 -showcerts
```

## Important Notes

- **Never commit private keys to Git**
- **Use strong TLS cipher suites**
- **Set minimum TLS version to 1.2 or higher**
- **Regularly renew certificates**
- **Monitor certificate expiration**
- **Use separate certificates for each node in production**