htl-reverse-proxy-tls-lab/challenges/easyrsa-hints.md

Easy-RSA Hint Card (optional)

Diese Hinweise koennen Teams nutzen, wenn sie bei der HTTPS-Challenge feststecken.

1) Easy-RSA installieren (WSL/Linux)

Fedora:

sudo dnf install -y easy-rsa openssl

Ubuntu/WSL:

sudo apt update
sudo apt install -y easy-rsa openssl

2) PKI vorbereiten

mkdir -p certs/easyrsa
cp -r /usr/share/easy-rsa/* certs/easyrsa/
cd certs/easyrsa
./easyrsa init-pki

3) CA erstellen

./easyrsa build-ca nopass

4) Server-Zertifikat fuer localhost

./easyrsa gen-req localhost nopass
./easyrsa --subject-alt-name="DNS:localhost,IP:127.0.0.1" sign-req server localhost

Wichtig: Das --subject-alt-name ist nicht optional. Moderne Clients (curl, Browser) ignorieren den CN und pruefen ausschliesslich den SAN. Ohne SAN scheitert curl https://localhost:8443 trotz korrekt importierter CA mit no alternative certificate subject name matches target host name.

5) Nur Runtime-Zertifikate bereitstellen (nicht komplette PKI mounten)

Nutze fuer den Container nur die benoetigten Laufzeitdateien:

• localhost.crt (Server-Zertifikat)
• localhost.key (Server-Private-Key)

Beispiel:

mkdir -p ../../live
cp pki/issued/localhost.crt ../../live/
cp pki/private/localhost.key ../../live/
chmod 600 ../../live/localhost.key

Warum nicht die ganze PKI mounten?

• In pki/ liegen CA-relevante Dateien.
• Runtime-Container sollen keine unnoetigen PKI/CA-Dateien sehen.
• Prinzip: minimal noetige Secrets in Runtime.

Danach in proxy/nginx.conf TLS aktivieren und in docker-compose.yml Port 443 + Cert-Volume mappen.

Compose-Mindestbeispiel

services:
  reverse-proxy:
    ports:
      - "${HTTP_PORT:-8080}:80"
      - "${HTTPS_PORT:-8443}:443"
    volumes:
      - ./proxy/nginx.conf:/etc/nginx/nginx.conf:ro,z
      - ./proxy/html:/usr/share/nginx/html:ro,z
      - ./certs/live:/etc/nginx/certs:ro,z

Nginx-Mindestbeispiel (HTTP + HTTPS)

server {
  listen 80;
  server_name _;

  location = /healthz {
    default_type text/plain;
    return 200 "ok\n";
  }

  location / {
    return 301 https://$host:8443$request_uri;
  }
}

server {
  listen 443 ssl;
  server_name localhost;

  ssl_certificate /etc/nginx/certs/localhost.crt;
  ssl_certificate_key /etc/nginx/certs/localhost.key;
  ssl_protocols TLSv1.2 TLSv1.3;
  add_header Strict-Transport-Security "max-age=3600; includeSubDomains" always;

  add_header X-Content-Type-Options "nosniff" always;
  add_header X-Frame-Options "DENY" always;
  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
  add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
  add_header Cross-Origin-Opener-Policy "same-origin" always;
  add_header Cross-Origin-Resource-Policy "same-origin" always;

  location /service/a {
    proxy_pass http://backend_a/;
  }

  location /service/b {
    proxy_pass http://backend_b/;
  }
}

6) Root-CA importieren (Trust Store)

Wichtig: In den Trust-Store der Umgebung importieren, in der du testest.

• Test mit curl aus WSL (der Standardweg im Workshop): in den Linux-Trust-Store importieren -> Ubuntu/Debian-Befehle unten.
• Test im Windows-Browser: zusaetzlich der Windows-Import (certutil).

Fedora:

sudo cp certs/easyrsa/pki/ca.crt /etc/pki/ca-trust/source/anchors/htl-workshop-root-ca.crt
sudo update-ca-trust

Ubuntu/Debian:

sudo cp certs/easyrsa/pki/ca.crt /usr/local/share/ca-certificates/htl-workshop-root-ca.crt
sudo update-ca-certificates

Windows (PowerShell als Admin, optional):

certutil -addstore -f Root C:\path\to\ca.crt

7) Test ohne -k

Nach Import sollte HTTPS ohne Insecure-Flag funktionieren:

curl https://localhost:8443/service/a

Falls CA nicht global importiert ist:

curl --cacert certs/easyrsa/pki/ca.crt https://localhost:8443/service/a

8) Typische Fehlerbilder

• curl: (60) SSL certificate problem -> Root-CA nicht importiert oder falsche CA.
• Browser war offen waehrend CA-Import -> Browser neu starten.
• permission denied beim Nginx-Config-Mount (Fedora/SELinux) -> Volumes mit :z mounten.
• Zertifikat ohne localhost -> SAN/CN passt nicht zum Hostnamen.