Joachim Hummel
5cf4799054
Translate project documentation from English to German for better accessibility. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
Diese Datei bietet Anleitungen für Claude Code (claude.ai/code) bei der Arbeit mit Code in diesem Repository.
|
|
|
|
## Projektübersicht
|
|
|
|
Dies ist ein Python PBKDF2 Passwort-Hashing-Tool mit zwei Implementierungen:
|
|
- `salt.py`: Referenzimplementierung mit CLI, die sowohl `hash` als auch `verify` Unterbefehle unterstützt, plus eine Abkürzung, bei der `python3 salt.py <password>` automatisch den hash-Befehl aufruft
|
|
- `salt2.py`: Alternative CLI, die aus `salt.py` importiert und explizite Unterbefehle erfordert (`generate` und `verify`)
|
|
|
|
Beide Implementierungen verwenden PBKDF2-HMAC-SHA256 mit konfigurierbarer Iterationsanzahl (Standard: 200.000, überschreibbar über die Umgebungsvariable `PBKDF2_ITERATIONS`).
|
|
|
|
## Häufige Befehle
|
|
|
|
### CLI ausführen
|
|
```bash
|
|
# Passwort hashen (salt.py unterstützt Abkürzungssyntax)
|
|
python3 salt.py "MeinPasswort"
|
|
python3 salt.py hash "MeinPasswort"
|
|
|
|
# Passwort verifizieren
|
|
python3 salt.py verify <passwort> <salt_b64> <hash_b64>
|
|
|
|
# Alternative CLI (erfordert explizite Unterbefehle)
|
|
python3 salt2.py generate "MeinPasswort"
|
|
python3 salt2.py verify <passwort> <salt_b64> <hash_b64>
|
|
```
|
|
|
|
### Testen
|
|
```bash
|
|
# Alle Tests ausführen
|
|
python3 -m pytest
|
|
|
|
# Spezifische Tests mit ausführlicher Ausgabe ausführen
|
|
python3 -m pytest -k verify --maxfail=1 -vv
|
|
|
|
# Tests für ein bestimmtes Modul ausführen
|
|
python3 -m pytest tests/test_hashing.py
|
|
```
|
|
|
|
### Abhängigkeiten
|
|
Abhängigkeiten sind in `requirements.txt` aufgelistet. Installation mit:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Code-Architektur
|
|
|
|
### Modulstruktur
|
|
- **salt.py**: Kernmodul mit den Funktionen `hash_password()` und `verify_password()` sowie einer integrierten CLI über `main()`
|
|
- **salt2.py**: Wrapper-CLI, die aus `salt.py` importiert und eine alternative Befehlsstruktur bietet
|
|
- **tests/**: Test-Suite, die die Modulstruktur widerspiegelt
|
|
- `test_hashing.py`: Tests für Kern-Hashing-/Verifizierungsfunktionen
|
|
- `test_cli.py`: Tests für CLI-Verhalten (speziell die Abkürzungssyntax von `salt.py`)
|
|
|
|
### Hauptfunktionen
|
|
|
|
**`hash_password(password, *, iterations=None, salt_bytes=16) -> tuple[str, str]`**
|
|
- Generiert ein kryptographisch sicheres zufälliges Salt
|
|
- Leitet einen Hash mit PBKDF2-HMAC-SHA256 ab
|
|
- Gibt ein base64-kodiertes (Salt, Hash) Tupel zurück
|
|
|
|
**`verify_password(password, salt_b64, hash_b64, *, iterations=None) -> bool`**
|
|
- Validiert ein Passwort gegen gespeichertes Salt/Hash
|
|
- Verwendet zeitkonstanten Vergleich über `hmac.compare_digest()`
|
|
- Gibt `False` bei ungültigem base64 zurück, ohne Exceptions auszulösen
|
|
|
|
### CLI-Argumentbehandlung
|
|
Das Modul `salt.py` enthält `_normalize_args()`, welches die Abkürzungssyntax ermöglicht: Wenn das erste Argument kein Unterbefehl (`hash`/`verify`) und kein Flag ist, wird automatisch `hash` vorangestellt. Dies wird in `tests/test_cli.py:test_main_supports_hash_shortcut()` getestet.
|
|
|
|
## Entwicklungsrichtlinien
|
|
|
|
### Python-Version und Stil
|
|
- Ziel-Python-Version: 3.11+
|
|
- Typannotationen für öffentliche Funktionen verwenden
|
|
- 4-Leerzeichen-Einrückung
|
|
- `lowercase_with_underscores` Namenskonvention für Funktionen und Variablen befolgen
|
|
|
|
### Sicherheitspraktiken
|
|
- Immer `os.urandom()` für Salt-Generierung verwenden (niemals vorhersagbare Werte)
|
|
- `hmac.compare_digest()` für Hash-Vergleich verwenden, um Timing-Angriffe zu verhindern
|
|
- Base64-Eingabe mit `validate=True` Parameter validieren
|
|
- Kodierungsfehler elegant behandeln, indem `False` zurückgegeben wird statt Exceptions auszulösen
|
|
|
|
### Testanforderungen
|
|
- Tests in `tests/test_<modul>.py` platzieren, passend zum Modulnamen
|
|
- Happy Paths und Fehlerbehandlung abdecken (ungültiges base64, falsche Passwörter)
|
|
- Round-Trip-Tests einschließen: hash → verify mit korrekten/inkorrekten Passwörtern
|
|
- >90% Coverage für Hashing-Utilities aufrechterhalten
|
|
- Bei Hinzufügen neuer Hash-Algorithmen Regressionstests mit bekannten Salt/Hash-Paaren einschließen
|
|
|
|
### Konfiguration
|
|
- Iterationsanzahl standardmäßig 200.000, berücksichtigt aber die Umgebungsvariable `PBKDF2_ITERATIONS`
|
|
- Salt-Größe standardmäßig 16 Bytes (konfigurierbar über `salt_bytes` Parameter)
|
|
|
|
## Commit-Richtlinien
|
|
|
|
Imperativ formulierte Betreffzeilen mit konventionellen Commit-Präfixen verwenden:
|
|
- `feat:` für neue Features
|
|
- `fix:` für Fehlerbehebungen
|
|
- `test:` für Test-Hinzufügungen/-Änderungen
|
|
- `refactor:` für Code-Umstrukturierung
|
|
|
|
Issues mit `Fixes #ID` referenzieren, wenn zutreffend. PRs sollten erst nach erfolgreichen Tests eröffnet werden.
|