Fehlerbehebung

Fehlerbehebung

Diagnostizieren und beheben Sie häufige Probleme mit dem DuoKey AWS XKS Proxy

Gilt für:

AWS XKS ProxyConnectivity IssuesError Resolution

Schnelle Diagnose-Checkliste

Voraussetzungen

• Verbindungsstatus des External Key Store überprüft
• Health-Endpunkt des XKS-Proxy antwortet
• Netzwerkkonnektivität von AWS zum Proxy bestätigt
• TLS-Zertifikate gültig und nicht abgelaufen
• SigV4-Authentifizierungsdaten korrekt
• Externer Schlüssel im Schlüsselmanager vorhanden
• Externer Schlüsselmanager vom Proxy aus erreichbar
• Aktuelle CloudWatch-Metriken zeigen Aktivität
• Proxy-Protokolle zeigen aktuelle Anfragen

Häufige Probleme

1. XksProxyUriUnreachableException

Warnung

Fehler:XksProxyUriUnreachableException: The XKS proxy URI endpoint is unreachable

Mögliche Ursachen:

• XKS-Proxy ist ausgefallen oder wird nicht ausgeführt
• Netzwerkkonnektivitätsprobleme
• Firewall blockiert AWS-KMS-IP-Bereiche
• DNS-Auflösungsfehler
• Probleme mit dem TLS-Zertifikat

Konnektivität diagnostizierenBASH

# 1. Check if proxy is running
curl -k https://your-proxy-address.com/health

# 2. Check DNS resolution
nslookup your-proxy-address.com
dig your-proxy-address.com

# 3. Check TLS certificate
echo | openssl s_client -connect your-proxy-address.com:443 -servername your-proxy-address.com

# 4. Check proxy logs
tail -f /var/log/duokey-xks-proxy/proxy.log

---

2. XksProxyInvalidResponseException

Warnung

Fehler:XksProxyInvalidResponseException: The XKS proxy returned an invalid response

Mögliche Ursachen:

• Proxy entspricht nicht der Spezifikation der AWS XKS Proxy-API
• Probleme mit der JSON-Formatierung in Proxy-Antworten
• Falsche HTTP-Statuscodes
• Fehlende erforderliche Antwortfelder

---

3. XksProxyIncorrectAuthenticationCredentialException

Warnung

Fehler:XksProxyIncorrectAuthenticationCredentialException: Authentication credential is incorrect

Mögliche Ursachen:

• Nichtübereinstimmung der SigV4-Anmeldedaten zwischen AWS und Proxy
• Anmeldedaten abgelaufen oder rotiert
• Uhrzeitabweichung (Clock Skew) zwischen AWS und Proxy

---

4. XksKeyNotFoundException

Warnung

Fehler:XksKeyNotFoundException: External key not found

Mögliche Ursachen:

• Nichtübereinstimmung der Schlüssel-ID (Groß-/Kleinschreibung beachten)
• Schlüssel aus dem externen Schlüsselmanager gelöscht
• Falsches Schlüssel-Backend konfiguriert
• Routing-Problem im DuoKey Cockpit

---

5. Probleme mit hoher Latenz

Symptome: Vorgänge dauern länger als 100 ms bis zum Abschluss

Mögliche Ursachen:

• Netzwerklatenz zwischen AWS und Proxy
• Leistungsprobleme des externen Schlüsselmanagers
• Ressourcenbeschränkungen des Proxy
• Geografische Entfernung

---

6. Probleme mit TLS-Zertifikaten

Symptome: TLS-Handshake-Fehler oder Zertifikatswarnungen

Mögliche Ursachen:

• Abgelaufene Zertifikate
• Zertifikatskette unvollständig
• Falsches Zertifikat für die Domäne
• Zertifikat wird von AWS nicht als vertrauenswürdig eingestuft

---

7. External Key Store getrennt

Symptome: External Key Store wird als getrennt angezeigt

Erweiterte Fehlerbehebung

Debug-Modus

Debug-Protokollierung aktivierenYAML

# config.yml
logging:
level: debug
components:
  authentication: debug
  encryption: debug
  routing: debug
  backend: debug

Debug-Protokolle überprüfenBASH

systemctl restart duokey-xks-proxy
tail -f /var/log/duokey-xks-proxy/proxy.log | jq .

Paketerfassung

Netzwerkverkehr erfassenBASH

# Capture HTTPS traffic to/from proxy
tcpdump -i any -s 0 -w /tmp/xks-traffic.pcap port 443

# Analyze with Wireshark
wireshark /tmp/xks-traffic.pcap

Debugging des Health Checks

Detaillierter Health CheckBASH

# Detailed health check
curl -v https://your-proxy:443/kms/xks/v1/health \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

# Expected response:
# {
# "status": "OK",
# "version": "1.0",
# "keyManagers": [
# {
# "name": "vault-primary",
# "status": "ACTIVE"
# }
# ]
# }

Referenz der Fehlercodes

Fehlercode	Beschreibung	Häufige Ursachen
XksProxyUriUnreachableException	Proxy nicht erreichbar	Netzwerk, Firewall, Proxy ausgefallen
XksProxyInvalidResponseException	Ungültige Proxy-Antwort	API-Konformität, Fehler
XksProxyIncorrectAuthenticationCredentialException	Authentifizierungsfehler	Falsche Anmeldedaten, Uhrzeitabweichung
XksKeyNotFoundException	Externer Schlüssel nicht gefunden	Falsche Schlüssel-ID, Schlüssel gelöscht
XksKeyInvalidConfigurationException	Schlüsselkonfiguration ungültig	Falscher Schlüsseltyp, Schlüssel deaktiviert
XksProxyInvalidConfigurationException	Proxy-Konfiguration ungültig	Falsche URL, ungültige Einstellungen

Hilfe erhalten

Vor der Kontaktaufnahme mit dem Support

Diagnoseinformationen sammelnBASH

# 1. System information
uname -a
cat /etc/os-release

# 2. Proxy version and status
/usr/local/bin/duokey-xks-proxy --version
systemctl status duokey-xks-proxy

# 3. Recent logs
tail -100 /var/log/duokey-xks-proxy/proxy.log > proxy-logs.txt

# 4. External key store status
aws kms describe-custom-key-stores \
  --custom-key-store-id cks-xxxxx > keystore-status.json

# 5. CloudWatch metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/KMS \
  --metric-name XksProxyLatency \
  --dimensions Name=CustomKeyStoreId,Value=cks-xxxxx \
  --start-time $(date -u -d '1 hour ago' '+%Y-%m-%dT%H:%M:%S') \
  --end-time $(date -u '+%Y-%m-%dT%H:%M:%S') \
  --period 300 \
  --statistics Average,Maximum > cloudwatch-metrics.json

# 6. Network test results
curl -v https://your-proxy:443/health > network-test.txt 2>&1

Kontaktinformationen

Ressource	Kontakt
DuoKey-Support	[email protected]
AWS-Support	Fall in der AWS-Konsole eröffnen
Community	GitHub Discussions

Vorbeugende Maßnahmen

Regelmäßige Health Checks

Automatisiertes Health-Check-SkriptBASH

#!/bin/bash
# /usr/local/bin/xks-health-check.sh

PROXY_URL="https://your-proxy:443/health"
ALERT_EMAIL="[email protected]"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $PROXY_URL)

if [ "$RESPONSE" != "200" ]; then
  echo "XKS Proxy health check failed: HTTP $RESPONSE" | \
      mail -s "XKS Proxy Alert" $ALERT_EMAIL
  exit 1
fi

exit 0

Health Check planenBASH

# Add to cron
*/5 * * * * /usr/local/bin/xks-health-check.sh

Regelmäßiger Wartungsplan

Häufigkeit	Aufgabe
Wöchentlich	Protokolle und Metriken überprüfen
Monatlich	Disaster-Recovery-Verfahren testen
Vierteljährlich	Anmeldedaten rotieren
Jährlich	TLS-Zertifikate erneuern

Nächste Schritte

Schlüsselverwaltung

Verwalten Sie Ihre KMS-Schlüssel

Monitoring

Umfassendes Monitoring einrichten

Erste Schritte

Zurück zur Einrichtungsanleitung

Siehe auch

• Schlüsselverwaltung
• Monitoring
• Erste Schritte