Inhaltsverzeichnis

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:

« <- Security | -> Renew Certificate »

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

, , , , ,