====== Runbook: Set Up TLS ======

<WRAP round info>
**Duration:** ~15 minutes \\
**Role:** Security Admin \\
**Prerequisite:** Certificate (PFX or PEM+KEY)
</WRAP>

Enable HTTPS for the Data Gateway.

----

===== Workflow =====

<mermaid>
flowchart TD
    A[Start] --> B{Certificate available?}
    B -->|No| C[Obtain certificate]
    B -->|Yes| D[Adjust appsettings.json]
    C --> D
    D --> E[Restart Gateway]
    E --> F[Test HTTPS]
    F --> G{Successful?}
    G -->|Yes| H[Disable HTTP]
    G -->|No| I[Check logs]
    H --> J[Done]

    style J fill:#e8f5e9
    style I fill:#ffebee
</mermaid>

----

===== 1. Obtain Certificate =====

**Option A: Let's Encrypt (free)**

<code bash>
# Install certbot
sudo apt install certbot

# Request certificate
sudo certbot certonly --standalone -d gateway.example.com

# Result:
# /etc/letsencrypt/live/gateway.example.com/fullchain.pem
# /etc/letsencrypt/live/gateway.example.com/privkey.pem
</code>

**Option B: Self-signed (test only!)**

<code bash>
# Create self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes \
    -subj "/CN=gateway.example.com"

# Convert to PFX
openssl pkcs12 -export -out gateway.pfx -inkey key.pem -in cert.pem -passout pass:changeit
</code>

**Option C: Internal CA**

-> See [[..:..:..:..:..:pqcrypt:szenarien:operator:tagesgeschaeft:zertifikat-ausstellen|PQ Crypto: Issue Certificate]]

----

===== 2. Place Certificate =====

<code bash>
# Windows
mkdir %GATEWAY_ROOT%\certs
copy gateway.pfx %GATEWAY_ROOT%\certs\

# Linux
sudo mkdir -p /opt/data-gateway/certs
sudo cp cert.pem key.pem /opt/data-gateway/certs/
sudo chmod 600 /opt/data-gateway/certs/*
sudo chown datagateway:datagateway /opt/data-gateway/certs/*
</code>

----

===== 3. Configure appsettings.json =====

**With PFX file:**

<code json>
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "certs/gateway.pfx",
          "Password": "changeit"
        }
      }
    }
  }
}
</code>

**With PEM files:**

<code json>
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "certs/cert.pem",
          "KeyPath": "certs/key.pem"
        }
      }
    }
  }
}
</code>

**Enforce TLS version:**

<code json>
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "certs/gateway.pfx",
          "Password": "changeit"
        },
        "SslProtocols": ["Tls12", "Tls13"]
      }
    }
  }
}
</code>

----

===== 4. Restart Gateway =====

<code bash>
# Windows
Restart-Service -Name "DataGateway"

# Linux
sudo systemctl restart data-gateway

# Docker
docker restart gateway
</code>

----

===== 5. Test HTTPS =====

<code bash>
# Simple test
curl -k https://localhost/health

# With certificate verification
curl https://gateway.example.com/health

# Show TLS details
curl -v https://gateway.example.com/health 2>&1 | grep -E "SSL|TLS|subject|expire"

# OpenSSL test
openssl s_client -connect gateway.example.com:443 -servername gateway.example.com
</code>

----

===== 6. Disable HTTP (optional) =====

Allow only HTTPS:

<code json>
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:443",
        "Certificate": {
          "Path": "certs/gateway.pfx",
          "Password": "changeit"
        }
      }
    }
  }
}
</code>

Or HTTP->HTTPS redirect:

<code csharp>
// Program.cs
app.UseHttpsRedirection();
</code>

----

===== 7. Checklist =====

| # | Check | Done |
|---|-------|------|
| 1 | Certificate valid (not expired) | [ ] |
| 2 | Certificate for correct hostname | [ ] |
| 3 | Private key protected (chmod 600) | [ ] |
| 4 | HTTPS reachable | [ ] |
| 5 | TLS 1.2+ active | [ ] |
| 6 | HTTP disabled or redirect | [ ] |
| 7 | Firewall port 443 open | [ ] |

----

===== Troubleshooting =====

| Problem | Cause | Solution |
|---------|-------|----------|
| ''Unable to configure HTTPS'' | Wrong path | Check certificate path |
| ''Password incorrect'' | Wrong PFX password | Check password |
| ''Certificate expired'' | Certificate expired | New certificate |
| ''SSL_ERROR_RX_RECORD_TOO_LONG'' | HTTP instead of HTTPS | Check port/protocol |
| ''NET::ERR_CERT_COMMON_NAME_INVALID'' | CN/SAN wrong | Certificate with correct name |

----

===== Online SSL Test =====

For publicly reachable servers:

  * **SSL Labs:** [[https://www.ssllabs.com/ssltest/|ssllabs.com/ssltest]]
  * **Qualys:** Aim for grade A+

----

===== Related Runbooks =====

  * [[.:zertifikat-erneuern|Renew Certificate]] - Renewal process
  * [[.:firewall-regeln|Firewall Rules]] - Open port 443
  * [[..:monitoring:alerting|Alerting]] - Certificate monitoring

----

<< [[.:start|<- Security]] | [[.:zertifikat-erneuern|-> Renew Certificate]] >>

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Data Gateway Professional//

{{tag>operator runbook tls https zertifikat ssl}}