meldestelle/config/ssl/README.md

SSL/TLS Certificate Setup for Production

This directory contains SSL/TLS certificates and keys for securing the Meldestelle application in production.

Directory Structure

config/ssl/
├── postgres/          # PostgreSQL SSL certificates
├── redis/             # Redis TLS certificates
├── keycloak/          # Keycloak HTTPS certificates
├── prometheus/        # Prometheus HTTPS certificates
├── grafana/           # Grafana HTTPS certificates
├── nginx/             # Nginx SSL certificates
└── README.md          # This file

Certificate Requirements

1. PostgreSQL SSL Certificates

Place the following files in config/ssl/postgres/:

• server.crt - Server certificate
• server.key - Server private key
• ca.crt - Certificate Authority certificate

2. Redis TLS Certificates

Place the following files in config/ssl/redis/:

• redis.crt - Redis server certificate
• redis.key - Redis server private key
• ca.crt - Certificate Authority certificate
• redis.dh - Diffie-Hellman parameters

3. Keycloak HTTPS Certificates

Place the following files in config/ssl/keycloak/:

• server.crt.pem - Server certificate in PEM format
• server.key.pem - Server private key in PEM format

4. Prometheus HTTPS Certificates

Place the following files in config/ssl/prometheus/:

• prometheus.crt - Prometheus server certificate
• prometheus.key - Prometheus server private key
• web.yml - Prometheus web configuration file

5. Grafana HTTPS Certificates

Place the following files in config/ssl/grafana/:

• server.crt - Grafana server certificate
• server.key - Grafana server private key

6. Nginx SSL Certificates

Place the following files in config/ssl/nginx/:

• server.crt - Main SSL certificate
• server.key - Main SSL private key
• dhparam.pem - Diffie-Hellman parameters

Generating Self-Signed Certificates (Development/Testing)

⚠️ Warning: Only use self-signed certificates for development and testing. Use proper CA-signed certificates in production.

Generate CA Certificate

# Create CA private key
openssl genrsa -out ca.key 4096

# Create CA certificate
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/C=AT/ST=Vienna/L=Vienna/O=Meldestelle/OU=IT/CN=Meldestelle-CA"

Generate Server Certificates

# For each service, generate private key and certificate signing request
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/C=AT/ST=Vienna/L=Vienna/O=Meldestelle/OU=IT/CN=your-domain.com"

# Sign the certificate with CA
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt

# Clean up
rm server.csr

Generate Diffie-Hellman Parameters

openssl dhparam -out dhparam.pem 2048

Production Certificate Setup

Option 1: Let's Encrypt (Recommended)

Use Certbot to obtain free SSL certificates:

# Install certbot
sudo apt-get install certbot

# Obtain certificates
sudo certbot certonly --standalone -d your-domain.com -d www.your-domain.com

# Copy certificates to appropriate directories
sudo cp /etc/letsencrypt/live/your-domain.com/fullchain.pem config/ssl/nginx/server.crt
sudo cp /etc/letsencrypt/live/your-domain.com/privkey.pem config/ssl/nginx/server.key

Option 2: Commercial CA

1. Generate Certificate Signing Requests (CSRs)
2. Submit CSRs to your Certificate Authority
3. Download signed certificates
4. Place certificates in appropriate directories

Option 3: Internal CA

If using an internal Certificate Authority:

1. Generate CSRs for each service
2. Sign certificates with your internal CA
3. Distribute CA certificate to all clients

File Permissions

Ensure proper file permissions for security:

# Set restrictive permissions on private keys
chmod 600 config/ssl/*/server.key
chmod 600 config/ssl/*/redis.key
chmod 600 config/ssl/*/prometheus.key

# Set readable permissions on certificates
chmod 644 config/ssl/*/server.crt
chmod 644 config/ssl/*/ca.crt

# Set directory permissions
chmod 755 config/ssl/*/

Docker Volume Mounts

The certificates are mounted as read-only volumes in the Docker containers:

volumes:
  - ./config/ssl/nginx:/etc/ssl/nginx:ro
  - ./config/ssl/keycloak:/opt/keycloak/conf:ro
  # ... other mounts

Certificate Renewal

Automated Renewal (Let's Encrypt)

Set up a cron job for automatic renewal:

# Add to crontab
0 12 * * * /usr/bin/certbot renew --quiet --post-hook "docker-compose -f docker-compose.prod.yml restart nginx"

Manual Renewal

1. Generate new certificates
2. Replace old certificates in SSL directories
3. Restart affected services:

   docker-compose -f docker-compose.prod.yml restart nginx keycloak grafana prometheus
   

Security Best Practices

1. Use Strong Encryption: Use at least 2048-bit RSA keys or 256-bit ECDSA keys
2. Regular Rotation: Rotate certificates regularly (annually or bi-annually)
3. Secure Storage: Store private keys securely and limit access
4. Monitor Expiration: Set up monitoring for certificate expiration
5. Use HSTS: Enable HTTP Strict Transport Security
6. Perfect Forward Secrecy: Use ECDHE cipher suites
7. Certificate Transparency: Monitor CT logs for unauthorized certificates

Troubleshooting

Common Issues

1. Permission Denied

   # Fix file permissions
   sudo chown -R $USER:$USER config/ssl/
   chmod -R 755 config/ssl/
   chmod 600 config/ssl/*/server.key
   

2. Certificate Verification Failed

   # Verify certificate
   openssl x509 -in config/ssl/nginx/server.crt -text -noout
   
   # Check certificate chain
   openssl verify -CAfile config/ssl/nginx/ca.crt config/ssl/nginx/server.crt
   

3. TLS Handshake Errors

   • Check certificate validity dates
   • Verify certificate matches hostname
   • Ensure proper cipher suite configuration

Testing SSL Configuration

# Test SSL certificate
openssl s_client -connect your-domain.com:443 -servername your-domain.com

# Test with specific protocol
openssl s_client -connect your-domain.com:443 -tls1_2

# Check certificate expiration
openssl x509 -in config/ssl/nginx/server.crt -noout -dates

Support

For certificate-related issues:

1. Check service logs: docker-compose -f docker-compose.prod.yml logs [service-name]
2. Verify certificate files exist and have correct permissions
3. Test SSL configuration with OpenSSL tools
4. Consult service-specific SSL documentation