password-security-python/CLAUDE.md

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

# 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

# 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:

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.