====== Runbook: Renew Certificate ======

<WRAP round info>
**Duration:** ~10 minutes \\
**Role:** Security Admin \\
**Frequency:** Every 90 days (Let's Encrypt) or annually
</WRAP>

Renewal of TLS certificate for the Data Gateway.

----

===== Workflow =====

<mermaid>
flowchart TD
    A[Expiry warning] --> B{Certificate type?}
    B -->|Let's Encrypt| C[certbot renew]
    B -->|Internal CA| D[Request new certificate]
    B -->|Commercial| E[Renew at provider]
    C --> F[Replace certificate]
    D --> F
    E --> F
    F --> G[Restart Gateway]
    G --> H[Test HTTPS]
    H --> I{OK?}
    I -->|Yes| J[Done]
    I -->|No| K[Restore old certificate]

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

----

===== 1. Check Expiry =====

<code bash>
# Check current certificate
openssl s_client -connect gateway.example.com:443 -servername gateway.example.com 2>/dev/null | \
    openssl x509 -noout -dates

# Days until expiry
echo | openssl s_client -connect gateway.example.com:443 2>/dev/null | \
    openssl x509 -noout -enddate | \
    cut -d= -f2 | \
    xargs -I {} bash -c 'echo "Days until expiry: $(( ($(date -d "{}" +%s) - $(date +%s)) / 86400 ))"'
</code>

----

===== 2a. Renew Let's Encrypt =====

<code bash>
# Automatic (if certbot correctly configured)
sudo certbot renew

# With pre/post hook for Gateway
sudo certbot renew \
    --pre-hook "systemctl stop data-gateway" \
    --post-hook "systemctl start data-gateway"

# Dry run (without actual renewal)
sudo certbot renew --dry-run
</code>

**Automation via cron:**

<code bash>
# /etc/cron.d/certbot-gateway
0 3 * * * root certbot renew --quiet --post-hook "systemctl reload data-gateway"
</code>

----

===== 2b. Renew Internal CA =====

<code bash>
# Create CSR
openssl req -new -key gateway.key -out gateway.csr \
    -subj "/CN=gateway.example.com/O=Example Corp"

# Send CSR to CA (e.g., via PQ Crypto)
# -> New certificate: gateway-new.crt
</code>

See: [[..:..:..:..:..:pqcrypt:szenarien:operator:tagesgeschaeft:zertifikat-erneuern|PQ Crypto: Renew Certificate]]

----

===== 2c. Commercial Certificate =====

1. Log in at provider (DigiCert, GlobalSign, etc.)
2. Request renewal
3. Upload CSR or generate new
4. Complete validation
5. Download new certificate

----

===== 3. Backup Old Certificate =====

<code bash>
# Create backup
cp /opt/data-gateway/certs/gateway.pfx /opt/data-gateway/certs/gateway.pfx.bak.$(date +%Y%m%d)

# Or for PEM
cp /opt/data-gateway/certs/cert.pem /opt/data-gateway/certs/cert.pem.bak.$(date +%Y%m%d)
</code>

----

===== 4. Install New Certificate =====

<code bash>
# PEM format
sudo cp new-cert.pem /opt/data-gateway/certs/cert.pem
sudo cp new-key.pem /opt/data-gateway/certs/key.pem
sudo chmod 600 /opt/data-gateway/certs/*.pem

# PFX format
sudo cp new-gateway.pfx /opt/data-gateway/certs/gateway.pfx
sudo chmod 600 /opt/data-gateway/certs/gateway.pfx
</code>

----

===== 5. Restart Gateway =====

<code bash>
# Linux
sudo systemctl restart data-gateway

# Windows
Restart-Service -Name "DataGateway"

# Docker
docker restart gateway

# Kubernetes (Rolling Update)
kubectl rollout restart deployment/data-gateway -n data-gateway
</code>

----

===== 6. Verify =====

<code bash>
# New certificate active?
echo | openssl s_client -connect gateway.example.com:443 2>/dev/null | \
    openssl x509 -noout -subject -dates

# Health Check
curl https://gateway.example.com/health

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

----

===== 7. Rollback (if needed) =====

<code bash>
# Restore backup
sudo cp /opt/data-gateway/certs/gateway.pfx.bak.20241215 /opt/data-gateway/certs/gateway.pfx

# Restart Gateway
sudo systemctl restart data-gateway

# Verify
curl https://gateway.example.com/health
</code>

----

===== 8. Checklist =====

| # | Check | Done |
|---|-------|------|
| 1 | Old certificate backed up | [ ] |
| 2 | New certificate valid | [ ] |
| 3 | Hostnames match | [ ] |
| 4 | Certificate installed | [ ] |
| 5 | Gateway restarted | [ ] |
| 6 | HTTPS working | [ ] |
| 7 | Monitoring notified | [ ] |

----

===== Troubleshooting =====

| Problem | Cause | Solution |
|---------|-------|----------|
| ''Certificate mismatch'' | Key doesn't match | Regenerate key |
| ''Chain incomplete'' | Intermediate missing | Add chain file |
| ''Permission denied'' | Wrong permissions | chmod 600 |
| Gateway won't start | Wrong password | Check appsettings.json |

----

===== Automatic Monitoring =====

Prometheus alert for certificate expiry:

<code yaml>
- alert: GatewayCertExpiringSoon
  expr: |
    (probe_ssl_earliest_cert_expiry{job="gateway-tls"} - time()) / 86400 < 14
  for: 1h
  labels:
    severity: warning
  annotations:
    summary: "Gateway certificate expiring soon"
    description: "Certificate expires in {{ $value | humanize }} days."
</code>

----

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

  * [[.:tls-einrichten|Set Up TLS]] - Initial configuration
  * [[..:monitoring:alerting|Alerting]] - Expiry monitoring
  * [[..:..:..:..:..:pqcrypt:szenarien:operator:tagesgeschaeft:zertifikat-erneuern|PQ Crypto: Renew Certificate]]

----

<< [[.:tls-einrichten|<- Set Up TLS]] | [[.:firewall-regeln|-> Firewall Rules]] >>

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

{{tag>operator runbook zertifikat renewal tls}}