Skip to content

SSL-CERTIFICATES.md

Latest commit

 

History

History
350 lines (273 loc) · 8.37 KB

SSL-CERTIFICATES.md

File metadata and controls

350 lines (273 loc) · 8.37 KB

SSL Certificate Generation Guide

This guide explains how to create self-signed SSL certificates for HA VIP Manager when using HTTPS health checks or secure communication.

📋 Overview

HA VIP Manager can perform health checks over HTTPS and may require SSL certificates for secure communication. While production deployments should use certificates from a trusted Certificate Authority (CA), self-signed certificates are suitable for:

  • Development and testing environments
  • Internal networks with controlled certificate distribution
  • Kubernetes control plane internal communication
  • Lab and proof-of-concept deployments

⚠️ Security Considerations

Self-signed certificates provide encryption but NOT identity verification:

  • ✅ Traffic is encrypted between client and server
  • ❌ No protection against man-in-the-middle attacks
  • ❌ Browsers will show security warnings
  • ❌ Certificate chain validation will fail

For production use:

  • Use certificates from trusted CAs (Let's Encrypt, commercial CAs)
  • Implement proper certificate management and rotation
  • Consider using cert-manager in Kubernetes environments

🔧 Method 1: OpenSSL (Recommended)

Simple Self-Signed Certificate

# Generate private key and certificate in one command
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
    -days 365 -nodes \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=ha-vip"

# Set appropriate permissions
chmod 600 key.pem
chmod 644 cert.pem

Advanced Certificate with Subject Alternative Names (SAN)

# Create a configuration file for SAN
cat > cert.conf << EOF
[req]
default_bits = 4096
prompt = no
distinguished_name = req_distinguished_name
req_extensions = v3_req

[req_distinguished_name]
C = US
ST = State
L = City
O = Organization
OU = IT Department
CN = ha-vip

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = ha-vip
DNS.2 = ha-vip.local
DNS.3 = localhost
DNS.4 = *.ha-vip.local
IP.1 = 127.0.0.1
IP.2 = 192.168.1.100
IP.3 = 10.0.0.100
EOF

# Generate the certificate with SAN
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
    -days 365 -nodes -config cert.conf -extensions v3_req

# Clean up
rm cert.conf

Wildcard Certificate for Multiple Services

# For *.example.local domain
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
    -days 365 -nodes \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=*.example.local"

🔧 Method 2: Using mkcert (Developer-Friendly)

mkcert creates locally-trusted certificates:

# Install mkcert (macOS)
brew install mkcert

# Install mkcert (Linux)
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

# Install local CA
mkcert -install

# Generate certificate
mkcert -key-file key.pem -cert-file cert.pem \
    ha-vip localhost 127.0.0.1 192.168.1.100 ::1

🔧 Method 3: cfssl (Advanced)

For more sophisticated certificate management:

# Install cfssl
go install github.com/cloudflare/cfssl/cmd/cfssl@latest
go install github.com/cloudflare/cfssl/cmd/cfssljson@latest

# Create CA configuration
cat > ca-config.json << EOF
{
  "signing": {
    "default": {
      "expiry": "8760h"
    },
    "profiles": {
      "server": {
        "expiry": "8760h",
        "usages": [
          "signing",
          "key encipherment",
          "server auth"
        ]
      }
    }
  }
}
EOF

# Create certificate signing request
cat > cert-csr.json << EOF
{
  "CN": "ha-vip",
  "hosts": [
    "ha-vip",
    "localhost",
    "127.0.0.1",
    "192.168.1.100"
  ],
  "key": {
    "algo": "rsa",
    "size": 4096
  }
}
EOF

# Generate the certificate
cfssl gencert -config=ca-config.json -profile=server cert-csr.json | cfssljson -bare cert
mv cert.pem cert.pem
mv cert-key.pem key.pem

📁 File Organization

Organize certificates in your HA VIP Manager deployment:

# Create certificate directory
sudo mkdir -p /etc/ha-vip/certs
sudo chown ha-vip:ha-vip /etc/ha-vip/certs
sudo chmod 750 /etc/ha-vip/certs

# Copy certificates
sudo cp cert.pem /etc/ha-vip/certs/
sudo cp key.pem /etc/ha-vip/certs/
sudo chown ha-vip:ha-vip /etc/ha-vip/certs/*.pem
sudo chmod 644 /etc/ha-vip/certs/cert.pem
sudo chmod 600 /etc/ha-vip/certs/key.pem

⚙️ Configuration Examples

Basic HTTPS Health Check

# config.yaml
health_check:
  protocol: "https"
  host: "127.0.0.1"
  port: 6443
  path: "/readyz"
  tls:
    cert_file: "/etc/ha-vip/certs/cert.pem"
    key_file: "/etc/ha-vip/certs/key.pem"
    insecure_skip_verify: true  # For self-signed certificates

Client Certificate Authentication

# config.yaml
kubernetes:
  auth_type: "cert"
  cert_file: "/etc/ha-vip/certs/client-cert.pem"
  key_file: "/etc/ha-vip/certs/client-key.pem"
  ca_file: "/etc/ha-vip/certs/ca.pem"

🔄 Certificate Rotation

Automated Renewal Script

#!/bin/bash
# /usr/local/bin/renew-ha-vip-cert.sh

CERT_DIR="/etc/ha-vip/certs"
BACKUP_DIR="/etc/ha-vip/certs/backup"
SERVICE_NAME="ha-vip"

# Create backup
mkdir -p "$BACKUP_DIR"
cp "$CERT_DIR"/*.pem "$BACKUP_DIR/$(date +%Y%m%d_%H%M%S)/"

# Generate new certificate
openssl req -x509 -newkey rsa:4096 \
    -keyout "$CERT_DIR/key.pem.new" \
    -out "$CERT_DIR/cert.pem.new" \
    -days 365 -nodes \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=ha-vip"

# Set permissions
chmod 600 "$CERT_DIR/key.pem.new"
chmod 644 "$CERT_DIR/cert.pem.new"
chown ha-vip:ha-vip "$CERT_DIR"/*.pem.new

# Atomic replacement
mv "$CERT_DIR/cert.pem.new" "$CERT_DIR/cert.pem"
mv "$CERT_DIR/key.pem.new" "$CERT_DIR/key.pem"

# Restart service
systemctl restart "$SERVICE_NAME"

echo "Certificate renewed successfully"

Cron Job for Automatic Renewal

# Add to root's crontab
# Renew certificate monthly
0 2 1 * * /usr/local/bin/renew-ha-vip-cert.sh >> /var/log/ha-vip-cert-renewal.log 2>&1

🧪 Testing Certificates

Verify Certificate Information

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Check certificate and key match
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa -noout -modulus -in key.pem | openssl md5

# Test certificate with specific hostname
openssl s_client -connect localhost:6443 -servername ha-vip

Validate Certificate Chain

# For self-signed certificates
openssl verify -CAfile cert.pem cert.pem

# Check certificate expiration
openssl x509 -in cert.pem -noout -dates

🚨 Troubleshooting

Common Issues

  1. Permission Denied Errors

    # Fix file permissions
sudo chown ha-vip:ha-vip /etc/ha-vip/certs/*.pem
sudo chmod 600 /etc/ha-vip/certs/key.pem
sudo chmod 644 /etc/ha-vip/certs/cert.pem

  2. Certificate/Key Mismatch

    # Verify they match
diff <(openssl rsa -noout -modulus -in key.pem) \
     <(openssl x509 -noout -modulus -in cert.pem)

  3. Invalid Certificate Format

    # Check file format
file cert.pem key.pem
head -1 cert.pem key.pem

Debug Commands

# Check certificate is properly loaded
sudo journalctl -u ha-vip -f | grep -i cert

# Test HTTPS connection
curl -k https://localhost:6443/readyz

# Verbose SSL debugging
openssl s_client -connect localhost:6443 -debug -msg

📚 Best Practices

  1. File Security

    • Private keys should be readable only by the service user
    • Store certificates in a dedicated directory
    • Use proper file permissions (600 for keys, 644 for certificates)

  2. Certificate Management

    • Set reasonable expiration dates (1 year for testing, shorter for production)
    • Implement automated renewal before expiration
    • Keep backups of working certificates

  3. Subject Alternative Names

    • Include all hostnames/IPs the service will use
    • Use wildcard certificates for multiple subdomains
    • Include localhost and 127.0.0.1 for local testing

  4. Key Size and Algorithms

    • Use RSA 4096-bit or ECDSA P-384 for new certificates
    • Avoid deprecated algorithms (MD5, SHA-1)
    • Consider future cryptographic requirements

🔗 Related Documentation