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:
   ```bash
   # 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:
   ```bash
   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:
   ```bash
   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:**
```bash
curl https://5.83.148.129/api/v2/server/version \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Accept: application/json"
```

**Ohne SSL-Verifizierung:**
```bash
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:**
```bash
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
<?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:
```bash
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