Inhaltsverzeichnis

Runbook: Set Up TLS

Runbook: Set Up TLS

Duration: ~15 minutes
Role: Security Admin
Prerequisite: Certificate (PFX or PEM+KEY)

Enable HTTPS for the Data Gateway.

Workflow

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

1. Obtain Certificate

Option A: Let's Encrypt (free)

# 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

Option B: Self-signed (test only!)

# 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

Option C: Internal CA

→ See PQ Crypto: Issue Certificate

2. Place Certificate

# 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/*

3. Configure appsettings.json

With PFX file:

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

With PEM files:

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

Enforce TLS version:

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

4. Restart Gateway

# Windows
Restart-Service -Name "DataGateway"
 
# Linux
sudo systemctl restart data-gateway
 
# Docker
docker restart gateway

5. Test HTTPS

# 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

6. Disable HTTP (optional)

Allow only HTTPS:

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

Or HTTP→HTTPS redirect:

// Program.cs
app.UseHttpsRedirection();

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: ssllabs.com/ssltest
Qualys: Aim for grade A+

Related Runbooks

Renew Certificate - Renewal process
Firewall Rules - Open port 443
Alerting - Certificate monitoring

« <- Security | -> Renew Certificate »

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

operator, runbook, tls, https, zertifikat, ssl