KeyHelp-Manager-for-WHMCS/SSL_TROUBLESHOOTING.md

SSL-Fehlerbehebung - KeyHelp Manager Modul

Übersicht

Das KeyHelp Manager Modul verwendet SSL/TLS-Verbindungen zur sicheren Kommunikation mit der KeyHelp API. Bei der Verwendung von IP-Adressen oder selbstsignierten Zertifikaten können SSL-Verifizierungsprobleme auftreten.

Automatische SSL-Verifizierung

Das Modul erkennt automatisch, ob eine IP-Adresse verwendet wird und deaktiviert in diesem Fall die SSL-Zertifikatsverifizierung.

Wie es funktioniert

Hostname wird geprüft
    ↓
Ist es eine IP-Adresse? (z.B. 5.83.148.129)
    ↓
JA → SSL-Verifizierung wird automatisch deaktiviert
    ↓
NEIN → SSL-Verifizierung bleibt aktiv (Standard)

Häufige SSL-Fehler

1. cURL error 60: SSL certificate problem

Vollständige Fehlermeldung:

cURL error 60: SSL: no alternative certificate subject name matches target host name '5.83.148.129'

Ursache: Das SSL-Zertifikat wurde für einen Domain-Namen ausgestellt (z.B. server.example.com), aber Sie verwenden eine IP-Adresse zur Verbindung.

Lösung:

• ✅ Automatisch gelöst: Bei IP-Adressen deaktiviert das Modul die SSL-Verifizierung automatisch
• ✅ Keine manuelle Konfiguration nötig

Logging: Das Modul schreibt einen Hinweis in die Activity Logs:

KeyHelp Manager: SSL verification disabled for 5.83.148.129 (IP address detected)

---

2. Self-signed Certificate Error

Fehlermeldung:

cURL error 60: SSL certificate problem: self signed certificate

Ursache: Der KeyHelp-Server verwendet ein selbstsigniertes SSL-Zertifikat statt eines von einer vertrauenswürdigen Zertifizierungsstelle (CA) signierten Zertifikats.

Lösung:

Option A: SSL-Verifizierung manuell deaktivieren (nicht empfohlen für Produktion)

1. Öffnen Sie die Server-Konfiguration in WHMCS:

   • Navigieren Sie zu Setup → Products/Services → Servers
   • Bearbeiten Sie Ihren KeyHelp-Server

2. Tragen Sie im Feld HTTP Prefix den Wert ein:

   no-verify
   

3. Speichern Sie die Konfiguration

Logging:

KeyHelp Manager: SSL verification disabled for server.example.com (manual override)

Option B: Gültiges SSL-Zertifikat installieren (empfohlen)

1. Installieren Sie Let's Encrypt auf Ihrem KeyHelp-Server:

   # In KeyHelp unter System → SSL-Zertifikate
   

2. Generieren Sie ein kostenloses Let's Encrypt Zertifikat für Ihre Domain

3. Stellen Sie sicher, dass KeyHelp das Zertifikat für die API verwendet

4. Verwenden Sie den Domain-Namen statt der IP-Adresse in WHMCS

---

3. Certificate has expired

Fehlermeldung:

cURL error 60: SSL certificate problem: certificate has expired

Ursache: Das SSL-Zertifikat ist abgelaufen.

Lösung:

1. Erneuern Sie das SSL-Zertifikat auf dem KeyHelp-Server
2. Bei Let's Encrypt: Überprüfen Sie die automatische Erneuerung
3. Prüfen Sie das Ablaufdatum:

   openssl s_client -connect ihr-server.de:443 -servername ihr-server.de < /dev/null 2>/dev/null | openssl x509 -noout -dates
   

---

4. Unable to get local issuer certificate

Fehlermeldung:

cURL error 60: SSL certificate problem: unable to get local issuer certificate

Ursache: Die Zertifikatskette ist unvollständig oder das Root-Zertifikat fehlt.

Lösung:

1. Stellen Sie sicher, dass die vollständige Zertifikatskette auf dem KeyHelp-Server installiert ist
2. Prüfen Sie die Zertifikatskette:

   openssl s_client -connect ihr-server.de:443 -showcerts
   

3. Temporäre Lösung: Deaktivieren Sie die SSL-Verifizierung mit "no-verify"

---

Konfiguration

Server-Einstellungen in WHMCS

Setup → Products/Services → Servers → [Ihr KeyHelp Server]

┌─────────────────────────────────────────────┐
│ Name:         KeyHelp Server 1             │
│ Hostname:     5.83.148.129 ← IP-Adresse    │
│ Type:         KeyHelp Manager               │
│ Username:     [leer]                        │
│ Password:     [Ihr API-Key]                 │
│ Access Hash:  [leer]                        │
│ Secure:       ☑ On                          │
│ HTTP Prefix:  [leer] ← Auto bei IP         │
└─────────────────────────────────────────────┘

Bei IP-Adresse: Keine weitere Konfiguration nötig!

---

Manuelle Deaktivierung der SSL-Verifizierung

Setup → Products/Services → Servers → [Ihr KeyHelp Server]

┌─────────────────────────────────────────────┐
│ Name:         KeyHelp Server 1             │
│ Hostname:     server.example.com           │
│ Type:         KeyHelp Manager               │
│ Username:     [leer]                        │
│ Password:     [Ihr API-Key]                 │
│ Access Hash:  [leer]                        │
│ Secure:       ☑ On                          │
│ HTTP Prefix:  no-verify ← Manuell          │
└─────────────────────────────────────────────┘

---

Best Practices

✅ Empfohlen für Entwicklung/Test

• IP-Adresse verwenden (SSL-Verifizierung wird automatisch deaktiviert)
• Oder "no-verify" bei selbstsignierten Zertifikaten

✅ Empfohlen für Produktion

1. Verwenden Sie einen Domain-Namen statt einer IP-Adresse

   Statt:  5.83.148.129
   Nutzen: keyhelp.example.com
   

2. Installieren Sie ein gültiges SSL-Zertifikat

   • Let's Encrypt (kostenlos)
   • Commercial CA (Comodo, DigiCert, etc.)

3. DNS korrekt konfigurieren

   keyhelp.example.com → A Record → 5.83.148.129
   

4. SSL-Verifizierung aktiviert lassen

   • HTTP Prefix: [leer lassen]
   • Secure: On

⚠️ Sicherheitshinweise

Szenario	SSL-Verifizierung	Sicherheit	Empfohlen für
IP-Adresse mit gültigem Cert	Auto aus	Mittel	Test/Dev
Domain mit gültigem Cert	An	Hoch	Produktion
Selbstsigniertes Cert	Manuell aus	Niedrig	Nur Test
Abgelaufenes Cert	-	Unsicher	❌ Nie

---

Logs überprüfen

WHMCS Activity Log

System Settings → Activity Log

Filter nach: "KeyHelp Manager: SSL verification disabled"

Beispiel-Einträge:

KeyHelp Manager: SSL verification disabled for 5.83.148.129 (IP address detected)
KeyHelp Manager: SSL verification disabled for server.example.com (manual override)

WHMCS Module Log

Utilities → Logs → Module Log

Filter: keyhelpmanager

Hier sehen Sie alle API-Requests und Responses inkl. SSL-Fehlern.

---

Debugging

Test 1: Manuelle API-Verbindung

Mit SSL-Verifizierung:

curl https://5.83.148.129/api/v2/server/version \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Accept: application/json"

Ohne SSL-Verifizierung:

curl -k https://5.83.148.129/api/v2/server/version \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Accept: application/json"

Der -k Parameter entspricht verify => false in Guzzle.

---

Test 2: SSL-Zertifikat überprüfen

Zertifikat-Informationen anzeigen:

openssl s_client -connect 5.83.148.129:443 -servername keyhelp.example.com < /dev/null 2>/dev/null | openssl x509 -noout -text

Prüfen Sie:

• Subject: CN (Common Name)
• Subject Alternative Name (SAN)
• Validity: Not Before / Not After
• Issuer

---

Test 3: PHP Guzzle Test-Script

Erstellen Sie eine Test-Datei test_keyhelp_ssl.php:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$hostname = '5.83.148.129';
$apiKey = 'IHR_API_KEY';

// Test mit SSL-Verifizierung
$client = new Client([
    'verify' => true,
    'timeout' => 10,
]);

try {
    $response = $client->get("https://{$hostname}/api/v2/server/version", [
        'headers' => [
            'X-API-Key' => $apiKey,
            'Accept' => 'application/json',
        ],
    ]);
    echo "✅ Mit SSL-Verifizierung: Erfolg!\n";
    echo $response->getBody();
} catch (Exception $e) {
    echo "❌ Mit SSL-Verifizierung: Fehler!\n";
    echo $e->getMessage() . "\n\n";
}

// Test ohne SSL-Verifizierung
$client = new Client([
    'verify' => false,
    'timeout' => 10,
]);

try {
    $response = $client->get("https://{$hostname}/api/v2/server/version", [
        'headers' => [
            'X-API-Key' => $apiKey,
            'Accept' => 'application/json',
        ],
    ]);
    echo "✅ Ohne SSL-Verifizierung: Erfolg!\n";
    echo $response->getBody();
} catch (Exception $e) {
    echo "❌ Ohne SSL-Verifizierung: Fehler!\n";
    echo $e->getMessage();
}

Führen Sie aus:

php test_keyhelp_ssl.php

---

Zusammenfassung

IP-Adresse verwenden (Automatisch)

Hostname: 5.83.148.129
HTTP Prefix: [leer]
→ SSL-Verifizierung: Automatisch deaktiviert ✅

Domain mit selbstsigniertem Zertifikat (Manuell)

Hostname: server.example.com
HTTP Prefix: no-verify
→ SSL-Verifizierung: Manuell deaktiviert ✅

Domain mit gültigem Zertifikat (Empfohlen)

Hostname: keyhelp.example.com
HTTP Prefix: [leer]
→ SSL-Verifizierung: Aktiv ✅✅✅

---

Support

Bei weiteren SSL-Problemen:

1. WHMCS Module Log prüfen: Utilities → Logs → Module Log
2. Activity Log prüfen: System Settings → Activity Log
3. KeyHelp Logs prüfen: /var/log/keyhelp/
4. PHP Error Log prüfen: /var/log/php/error.log

Kontakt:

• E-Mail: info@avvgo.de
• Website: https://avvgo.de

---

Entwickelt von: Kevin Feiler / AVVGO
Version: 2.0.0
Letzte Aktualisierung: 2024