Initial commit
This commit is contained in:
216
backup 24.2.26 - Kopie (61)/security/handovers/STEP_6_2FA.md
Normal file
216
backup 24.2.26 - Kopie (61)/security/handovers/STEP_6_2FA.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user