Dépannage

Dépannage

Diagnostiquez et résolvez les problèmes courants du proxy DuoKey AWS XKS

S'applique à :

AWS XKS ProxyConnectivity IssuesError Resolution

Liste de contrôle de diagnostic rapide

Prérequis

• État de la connexion du magasin de clés externe vérifié
• Point de terminaison de santé du proxy XKS répondant
• Connectivité réseau d'AWS vers le proxy confirmée
• Certificats TLS valides et non expirés
• Identifiants d'authentification SigV4 corrects
• Clé externe existant dans le gestionnaire de clés
• Gestionnaire de clés externe accessible depuis le proxy
• Métriques CloudWatch récentes montrant une activité
• Journaux du proxy montrant des requêtes récentes

Problèmes courants

1. XksProxyUriUnreachableException

Avertissement

Erreur :XksProxyUriUnreachableException: The XKS proxy URI endpoint is unreachable

Causes possibles :

• Le proxy XKS est hors service ou ne fonctionne pas
• Problèmes de connectivité réseau
• Pare-feu bloquant les plages d'adresses IP d'AWS KMS
• Échec de la résolution DNS
• Problèmes de certificat TLS

Diagnose ConnectivityBASH

# 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

Avertissement

Erreur :XksProxyInvalidResponseException: The XKS proxy returned an invalid response

Causes possibles :

• Le proxy n'est pas conforme à la spécification de l'API du proxy AWS XKS
• Problèmes de formatage JSON dans les réponses du proxy
• Codes de statut HTTP incorrects
• Champs de réponse obligatoires manquants

---

3. XksProxyIncorrectAuthenticationCredentialException

Avertissement

Erreur :XksProxyIncorrectAuthenticationCredentialException: Authentication credential is incorrect

Causes possibles :

• Incohérence des identifiants SigV4 entre AWS et le proxy
• Identifiants expirés ou renouvelés
• Décalage d'horloge entre AWS et le proxy

---

4. XksKeyNotFoundException

Avertissement

Erreur :XksKeyNotFoundException: External key not found

Causes possibles :

• Incohérence de l'ID de clé (sensible à la casse)
• Clé supprimée du gestionnaire de clés externe
• Mauvais backend de clés configuré
• Problème de routage de DuoKey Cockpit

---

5. Problèmes de latence élevée

Symptômes : Opérations prenant plus de 100 ms à s'exécuter

Causes possibles :

• Latence réseau entre AWS et le proxy
• Problèmes de performance du gestionnaire de clés externe
• Contraintes de ressources du proxy
• Distance géographique

---

6. Problèmes de certificat TLS

Symptômes : Échecs de poignée de main TLS ou avertissements de certificat

Causes possibles :

• Certificats expirés
• Chaîne de certificats incomplète
• Mauvais certificat pour le domaine
• Certificat non approuvé par AWS

---

7. Magasin de clés externe déconnecté

Symptômes : Le magasin de clés externe apparaît comme déconnecté

Dépannage avancé

Mode débogage

Enable Debug LoggingYAML

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

Review Debug LogsBASH

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

Capture de paquets

Capture Network TrafficBASH

# 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

Débogage du contrôle de santé

Detailed 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"
# }
# ]
# }

Référence des codes d'erreur

Code d'erreur	Description	Causes courantes
XksProxyUriUnreachableException	Impossible d'atteindre le proxy	Réseau, pare-feu, proxy hors service
XksProxyInvalidResponseException	Réponse du proxy non valide	Conformité API, bogues
XksProxyIncorrectAuthenticationCredentialException	Échec d'authentification	Identifiants incorrects, décalage d'horloge
XksKeyNotFoundException	Clé externe introuvable	Mauvais ID de clé, clé supprimée
XksKeyInvalidConfigurationException	Configuration de clé non valide	Mauvais type de clé, clé désactivée
XksProxyInvalidConfigurationException	Configuration du proxy non valide	Mauvaise URL, paramètres non valides

Obtenir de l'aide

Avant de contacter le support

Gather Diagnostic InformationBASH

# 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

Coordonnées de contact

Ressource	Contact
Support DuoKey	[email protected]
Support AWS	Ouvrir un dossier dans la console AWS
Communauté	GitHub Discussions

Mesures préventives

Contrôles de santé réguliers

Automated Health Check ScriptBASH

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

Schedule Health CheckBASH

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

Calendrier de maintenance régulière

Fréquence	Tâche
Hebdomadaire	Examiner les journaux et les métriques
Mensuelle	Tester les procédures de reprise après sinistre
Trimestrielle	Effectuer la rotation des identifiants
Annuelle	Renouveler les certificats TLS

Étapes suivantes

Gestion des clés

Gérez vos clés KMS

Surveillance

Configurez une surveillance complète

Prise en main

Revenir au guide de configuration

Voir aussi

• Gestion des clés
• Surveillance
• Prise en main