aza/AzA march 2026/security/handovers/STEP_6_2FA.md

# STEP 6 – TOTP-ZWEI-FAKTOR-AUTHENTIFIZIERUNG
# Status: ABGESCHLOSSEN

---

## Architektur

### Komponenten

```
aza_totp.py          – Zentrales TOTP-Modul (RFC 6238)
basis14.py           – GUI-Integration (Login, Profil, Setup)
pyotp (2.9.0)        – TOTP-Implementierung (RFC 6238 kompatibel)
qrcode[pil] (8.2)    – QR-Code-Generierung
```

### Flow

```
Login-Dialog
    │
    ▼
Passwort prüfen ──► FAIL → Fehlermeldung
    │
    ▼ OK
2FA aktiv? ──► NEIN + 2FA_REQUIRED → Erzwinge 2FA-Setup
    │                                        │
    ▼ JA                                     ▼
TOTP-Dialog ──────────────────────── 2FA-Setup-Dialog
    │                                   │
    ▼                                   ▼
Code prüfen                        QR-Code scannen
    │                              Code validieren
    ├─ TOTP OK → Login              │
    ├─ Backup-Code OK → Login      Backup-Codes anzeigen
    └─ FAIL → Fehlermeldung         │
                                   2FA aktiviert
```

---

## Datenmodell

### Profil (kg_diktat_user_profile.json)

```json
{
  "name": "Dr. Beispiel",
  "specialty": "Dermatologie",
  "clinic": "Praxis XY",
  "password_hash": "$2b$12$...",
  "totp_active": true,
  "totp_secret_enc": "Base64-verschlüsselter-TOTP-Secret",
  "backup_codes": [
    "sha256-hash-code-1",
    "sha256-hash-code-2",
    "",
    "sha256-hash-code-4",
    ...
  ]
}
```

| Feld | Typ | Beschreibung |
|------|-----|-------------|
| `totp_active` | boolean | 2FA aktiviert/deaktiviert |
| `totp_secret_enc` | string | TOTP-Secret, XOR-verschlüsselt mit Passwort-Hash, Base64 |
| `backup_codes` | string[] | SHA-256-Hashes der Backup-Codes; leer = verbraucht |

---

## TOTP-Parameter

| Parameter | Wert |
|-----------|------|
| Algorithmus | TOTP (RFC 6238) |
| Hash | SHA-1 (Standard per RFC) |
| Zeitschritt | 30 Sekunden |
| Code-Länge | 6 Ziffern |
| Gültigkeitsfenster | +-1 (90 Sekunden total) |
| Secret-Länge | 160 bit (32 Base32-Zeichen) |

---

## Sicherheitsmassnahmen

### Secret-Verschlüsselung

- TOTP-Secret wird NIE im Klartext gespeichert
- Verschlüsselung: XOR mit SHA-256(Benutzer-Passwort)
- Encoding: Base64
- Entschlüsselung nur mit korrektem Passwort möglich
- Bei falschem Passwort: leerer String (kein Crash)

### Backup-Codes

- 8 Einmal-Codes (8 Zeichen, hex, uppercase)
- Gespeichert als SHA-256-Hashes
- Verbrauchte Codes werden zu leerem String
- Case-insensitive Eingabe
- HMAC-basierter Vergleich (timing-safe)

### Rate-Limiting

- Max. 5 TOTP-Versuche pro 5 Minuten pro Benutzer
- Nach Erreichen: auch korrekter Code wird blockiert
- Im RAM gehalten (Reset bei Neustart)

---

## ENV-Variablen

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `AZA_2FA_ENABLED` | `1` | 2FA-Feature verfügbar |
| `AZA_2FA_REQUIRED` | `0` | 2FA ist Pflicht für alle Benutzer |

### Verhalten

| AZA_2FA_ENABLED | AZA_2FA_REQUIRED | Ergebnis |
|:---:|:---:|---|
| 0 | 0 | 2FA komplett deaktiviert, kein Button im Profil |
| 1 | 0 | 2FA optional, Aktivierung im Profil |
| 1 | 1 | 2FA Pflicht, Setup nach erstem Login erzwungen |
| 0 | 1 | Feature deaktiviert, Required ignoriert |

---

## Recovery

- Wiederherstellung NUR über Backup-Codes
- Kein Admin-Reset ohne Prüfung
- Kein E-Mail-Recovery
- Backup-Codes werden nach 2FA-Aktivierung einmalig angezeigt
- Benutzer muss Codes selbst sichern (Kopieren/Ausdrucken)
- Bei aufgebrauchten Backup-Codes: Profil-Datei manuell bereinigen (Admin-Eingriff)

---

## Geänderte / Neue Dateien

| Datei | Änderung |
|-------|----------|
| `aza_totp.py` | NEU: Zentrales TOTP-Modul |
| `basis14.py` | Import: pyotp, qrcode, PIL.ImageTk, aza_totp |
| `basis14.py` | `_show_password_login()`: 2FA-Check nach Passwort |
| `basis14.py` | `_show_totp_login()`: NEU – TOTP-Code-Dialog |
| `basis14.py` | `_show_2fa_setup()`: NEU – QR-Code + Erst-Validierung |
| `basis14.py` | `_show_backup_codes()`: NEU – Backup-Code-Anzeige |
| `basis14.py` | `_show_profile_editor()`: 2FA-Aktivierung/Deaktivierung |

---

## Dependencies

```
pyotp==2.9.0       # TOTP RFC 6238
qrcode[pil]==8.2   # QR-Code-Generierung
```

---

## Testergebnis

```
24/24 PASS, 0/24 FAIL
GESAMTBEWERTUNG: PASS
```

| Test | Ergebnis |
|------|----------|
| Secret-Generierung (Base32, 32 Zeichen) | PASS |
| Secrets sind einzigartig | PASS |
| Provisioning URI (otpauth://) | PASS |
| URI enthält Issuer | PASS |
| URI enthält Secret | PASS |
| Korrekter Code akzeptiert | PASS |
| Falscher Code abgelehnt | PASS |
| Leerer Code abgelehnt | PASS |
| Abgelaufener Code (90s) abgelehnt | PASS |
| 8 Backup-Codes generiert | PASS |
| Code-Format (8 hex chars) | PASS |
| Codes einzigartig | PASS |
| Hashes SHA-256 | PASS |
| Backup-Code Lookup | PASS |
| Falscher Backup-Code abgelehnt | PASS |
| Case-insensitive | PASS |
| Einmalnutzung | PASS |
| Invalidierter Code abgelehnt | PASS |
| Secret-Verschlüsselung | PASS |
| Verschlüsselt != Klartext | PASS |
| Entschlüsselung korrekt | PASS |
| Falsches PW = falsches Secret | PASS |
| Rate-Limit greift nach 5 Versuchen | PASS |
| Rate-Limit blockiert auch korrekte Codes | PASS |

---

## Risiken

1. **XOR-Verschlüsselung:** Für eine Desktop-App akzeptabel, aber kryptographisch
   schwächer als AES. Upgrade auf Fernet/AES bei Bedarf.

2. **Secret an Passwort gebunden:** Bei Passwortänderung muss das TOTP-Secret
   neu verschlüsselt werden. Aktuell nicht automatisch – 2FA muss nach
   Passwortänderung neu eingerichtet werden.

3. **Rate-Limit im RAM:** Wird bei Neustart zurückgesetzt. Für Desktop-App
   akzeptabel (kein Netzwerk-Angriff möglich).

4. **Kein TOTP für workforce_planner:** Die 2FA ist nur im Desktop-Client
   (basis14.py) implementiert. Der workforce_planner (Web-API) hat noch
   keine 2FA-Integration.

5. **SHA-1 in TOTP:** RFC 6238 spezifiziert SHA-1 als Standard. Alle gängigen
   Authenticator-Apps (Google, Microsoft, Authy) erwarten SHA-1.