TLS Configuration¶
TLS Certificate Setup for MazeVault Deployment
Document Version: 1.0.0
Last Updated: 2026-02-10
1. Certificate Requirements¶
| Certificate | Purpose | Format | Minimum Key Size |
|---|---|---|---|
| Server TLS | HTTPS for Web Interface + API | PEM | RSA 2048 / ECDSA P-256 |
| OCSP TLS | HTTPS for OCSP Responder (optional) | PEM | RSA 2048 / ECDSA P-256 |
| Database SSL | PostgreSQL connection encryption | PEM | RSA 2048 |
| Agent mTLS CA | CA for agent client certificates | PEM | RSA 2048 |
2. Certificate Options¶
Option A: MazeVault Internal CA¶
Use MazeVault's built-in Certificate Authority to issue server certificates for internal deployments:
- Create a Root CA in MazeVault (Settings → Certificate Authorities → Create CA)
- Issue a server certificate for your domain
- Distribute the Root CA certificate to all clients as a trusted CA
Option B: Let's Encrypt (Public Internet)¶
For internet-facing deployments, use Let's Encrypt with cert-manager (Kubernetes) or certbot (on-premise):
Kubernetes (cert-manager):
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: mazevault-tls
namespace: mazevault
spec:
secretName: mazevault-tls
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
dnsNames:
- vault.example.com
On-Premise (certbot):
sudo certbot certonly --nginx -d vault.example.com
# Certificates stored in /etc/letsencrypt/live/vault.example.com/
Option C: Enterprise CA (Internal PKI)¶
Use your organization's existing PKI infrastructure to issue certificates:
- Generate a CSR on the MazeVault server
- Submit to your enterprise CA (Microsoft ADCS, Venafi, etc.)
- Install the issued certificate and CA chain
3. TLS Configuration — On-Premise¶
Certificate File Placement¶
/opt/mazevault/certs/
├── server.crt # Server certificate + intermediate CA chain
├── server.key # Private key (chmod 600)
└── ca.crt # Root CA certificate (for verification)
File Permissions¶
chmod 644 /opt/mazevault/certs/server.crt
chmod 600 /opt/mazevault/certs/server.key
chmod 644 /opt/mazevault/certs/ca.crt
chown root:root /opt/mazevault/certs/*
Nginx TLS Settings¶
The recommended TLS configuration for on-premise deployments:
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
4. TLS Configuration — Kubernetes¶
TLS Secret¶
kubectl create secret tls mazevault-tls \
--namespace mazevault \
--cert=server.crt \
--key=server.key
Ingress TLS¶
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: mazevault-ingress
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
tls:
- hosts:
- vault.example.com
secretName: mazevault-tls
5. Database SSL¶
PostgreSQL SSL Configuration¶
For standalone PostgreSQL:
# postgresql.conf
ssl = on
ssl_cert_file = '/var/lib/postgresql/certs/server.crt'
ssl_key_file = '/var/lib/postgresql/certs/server.key'
ssl_ca_file = '/var/lib/postgresql/certs/ca.crt'
ssl_min_protocol_version = 'TLSv1.2'
For Azure Database for PostgreSQL Flexible Server, SSL is enforced by default.
Connection String¶
| SSL Mode | Description | Recommended |
|---|---|---|
disable |
No SSL | ❌ |
require |
SSL required, no CA verification | ⚠️ Development only |
verify-ca |
SSL + CA certificate verification | ✅ |
verify-full |
SSL + CA + hostname verification | ✅ Production |
6. Certificate Renewal¶
Monitoring Expiry¶
MazeVault monitors TLS certificate expiry and raises alerts:
| Threshold | Alert Level |
|---|---|
| 30 days before expiry | Warning |
| 7 days before expiry | Critical |
Renewal Procedures¶
Let's Encrypt (auto-renewal):
Manual renewal:
1. Obtain new certificate from your CA
2. Replace files in /opt/mazevault/certs/
3. Reload Nginx: docker compose exec nginx nginx -s reload
Kubernetes (cert-manager): Renewal is automatic.
7. Verification¶
# Verify TLS configuration
openssl s_client -connect vault.example.com:443 -servername vault.example.com < /dev/null 2>/dev/null | openssl x509 -noout -dates -subject
# Check certificate chain
openssl s_client -connect vault.example.com:443 -showcerts < /dev/null
# Test with curl
curl -v https://vault.example.com/api/v1/health
8. Custom CA for Outgoing Connections (SMTP, LDAP, etc.)¶
If your SMTP server, LDAP directory, or other external service uses a certificate signed by a private / corporate CA, MazeVault's backend container must trust that CA. Without it, outgoing TLS connections will fail with:
Docker Compose¶
- Place your CA certificate (PEM format) in a path accessible to the host, e.g.
./certs/corporate-ca.crt. - Mount the certificate and update the trust store via an entrypoint override:
services:
mazevault-backend:
volumes:
- ./certs/corporate-ca.crt:/usr/local/share/ca-certificates/corporate-ca.crt:ro
entrypoint: ["/bin/sh", "-c", "update-ca-certificates && exec ./main"]
- Restart the service:
docker compose up -d mazevault-backend.
Kubernetes¶
Create a ConfigMap from the CA file and mount it:
apiVersion: v1
kind: ConfigMap
metadata:
name: corporate-ca
data:
corporate-ca.crt: |
-----BEGIN CERTIFICATE-----
<your CA certificate content>
-----END CERTIFICATE-----
---
# In the backend Deployment spec:
volumes:
- name: corporate-ca
configMap:
name: corporate-ca
containers:
- name: mazevault-backend
volumeMounts:
- name: corporate-ca
mountPath: /usr/local/share/ca-certificates/corporate-ca.crt
subPath: corporate-ca.crt
readOnly: true
command: ["/bin/sh", "-c", "update-ca-certificates && exec ./main"]
Verification¶
# From inside the running container:
docker exec mazevault-backend openssl s_client -connect smtp.example.com:587 -starttls smtp < /dev/null 2>&1 | head -20
A successful connection shows Verify return code: 0 (ok).
Related¶
- Azure AKS Deployment — Kubernetes TLS setup
- On-Premise Deployment — Nginx TLS configuration
- Encryption — Cryptographic standards