Joachim Hummel
f456538b11
Create user-friendly README based on CLAUDE.md documentation. Includes installation, usage examples, API reference, and development guidelines. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
164 lines
4.1 KiB
Markdown
164 lines
4.1 KiB
Markdown
# Python PBKDF2 Passwort-Hashing-Tool
|
|
|
|
Ein sicheres Python-Tool zum Hashen und Verifizieren von Passwörtern mit PBKDF2-HMAC-SHA256.
|
|
|
|
## Features
|
|
|
|
- **Zwei CLI-Implementierungen**: `salt.py` (mit Abkürzungssyntax) und `salt2.py` (explizite Befehle)
|
|
- **Sicherer Algorithmus**: PBKDF2-HMAC-SHA256 mit konfigurierbarer Iterationsanzahl
|
|
- **Kryptographisch sicheres Salt**: Generierung mit `os.urandom()`
|
|
- **Timing-Attack-Schutz**: Verwendung von `hmac.compare_digest()` für sichere Vergleiche
|
|
- **Flexible Konfiguration**: Anpassbare Iterationsanzahl über Umgebungsvariablen
|
|
- **Umfassende Tests**: >90% Coverage mit pytest
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Repository klonen
|
|
git clone https://git.unixweb.net/joachim/password-security-python.git
|
|
cd password-security-python
|
|
|
|
# Abhängigkeiten installieren
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Verwendung
|
|
|
|
### Passwort hashen
|
|
|
|
```bash
|
|
# Mit Abkürzungssyntax (salt.py)
|
|
python3 salt.py "MeinPasswort"
|
|
|
|
# Explizit mit hash-Befehl
|
|
python3 salt.py hash "MeinPasswort"
|
|
|
|
# Alternative CLI (salt2.py)
|
|
python3 salt2.py generate "MeinPasswort"
|
|
```
|
|
|
|
Ausgabe:
|
|
```
|
|
Salt: <base64-kodiertes-salt>
|
|
Hash: <base64-kodierter-hash>
|
|
```
|
|
|
|
### Passwort verifizieren
|
|
|
|
```bash
|
|
# Mit salt.py
|
|
python3 salt.py verify "MeinPasswort" <salt_b64> <hash_b64>
|
|
|
|
# Mit salt2.py
|
|
python3 salt2.py verify "MeinPasswort" <salt_b64> <hash_b64>
|
|
```
|
|
|
|
### Als Modul verwenden
|
|
|
|
```python
|
|
from salt import hash_password, verify_password
|
|
|
|
# Passwort hashen
|
|
salt_b64, hash_b64 = hash_password("MeinPasswort")
|
|
|
|
# Passwort verifizieren
|
|
is_valid = verify_password("MeinPasswort", salt_b64, hash_b64)
|
|
```
|
|
|
|
## Konfiguration
|
|
|
|
### Iterationsanzahl anpassen
|
|
|
|
Standardmäßig werden 200.000 Iterationen verwendet. Dies kann über die Umgebungsvariable `PBKDF2_ITERATIONS` angepasst werden:
|
|
|
|
```bash
|
|
export PBKDF2_ITERATIONS=300000
|
|
python3 salt.py "MeinPasswort"
|
|
```
|
|
|
|
### Salt-Größe anpassen
|
|
|
|
Die Salt-Größe kann beim Aufruf von `hash_password()` angepasst werden:
|
|
|
|
```python
|
|
salt_b64, hash_b64 = hash_password("MeinPasswort", salt_bytes=32)
|
|
```
|
|
|
|
## API-Referenz
|
|
|
|
### `hash_password(password, *, iterations=None, salt_bytes=16) -> tuple[str, str]`
|
|
|
|
Generiert einen sicheren Hash für das gegebene Passwort.
|
|
|
|
**Parameter:**
|
|
- `password` (str): Das zu hashende Passwort
|
|
- `iterations` (int, optional): Anzahl der PBKDF2-Iterationen (Standard: 200.000 oder `PBKDF2_ITERATIONS`)
|
|
- `salt_bytes` (int, optional): Größe des generierten Salts in Bytes (Standard: 16)
|
|
|
|
**Rückgabe:**
|
|
- Tupel aus (salt_base64, hash_base64)
|
|
|
|
### `verify_password(password, salt_b64, hash_b64, *, iterations=None) -> bool`
|
|
|
|
Verifiziert ein Passwort gegen gespeicherten Salt und Hash.
|
|
|
|
**Parameter:**
|
|
- `password` (str): Das zu verifizierende Passwort
|
|
- `salt_b64` (str): Base64-kodiertes Salt
|
|
- `hash_b64` (str): Base64-kodierter Hash
|
|
- `iterations` (int, optional): Anzahl der PBKDF2-Iterationen (Standard: 200.000 oder `PBKDF2_ITERATIONS`)
|
|
|
|
**Rückgabe:**
|
|
- `True` wenn das Passwort korrekt ist, `False` sonst
|
|
|
|
## Entwicklung
|
|
|
|
### Tests ausführen
|
|
|
|
```bash
|
|
# Alle Tests
|
|
python3 -m pytest
|
|
|
|
# Mit Verbose-Ausgabe
|
|
python3 -m pytest -vv
|
|
|
|
# Spezifische Tests
|
|
python3 -m pytest -k verify
|
|
```
|
|
|
|
### Code-Struktur
|
|
|
|
- **salt.py**: Kernmodul mit `hash_password()`, `verify_password()` und integrierter CLI
|
|
- **salt2.py**: Alternative CLI mit expliziten Befehlen
|
|
- **tests/**: Vollständige Test-Suite
|
|
- `test_hashing.py`: Tests für Hashing-/Verifizierungsfunktionen
|
|
- `test_cli.py`: Tests für CLI-Verhalten
|
|
- `test_algorithms.py`: Tests für Hash-Algorithmen
|
|
|
|
### Sicherheitspraktiken
|
|
|
|
- Kryptographisch sichere Zufallszahlen mit `os.urandom()`
|
|
- Timing-Attack-Schutz durch `hmac.compare_digest()`
|
|
- Validierung von Base64-Eingaben mit `validate=True`
|
|
- Elegante Fehlerbehandlung ohne Exception-Raising
|
|
|
|
## Anforderungen
|
|
|
|
- Python 3.11+
|
|
- pytest >= 7.4
|
|
- argon2-cffi >= 23.1.0
|
|
- bcrypt >= 4.1.0
|
|
|
|
## Lizenz
|
|
|
|
Siehe LICENSE-Datei im Repository.
|
|
|
|
## Beitragen
|
|
|
|
Pull Requests sind willkommen! Bitte stelle sicher, dass:
|
|
- Alle Tests erfolgreich durchlaufen
|
|
- Die Code-Coverage >90% bleibt
|
|
- Konventionelle Commit-Nachrichten verwendet werden (`feat:`, `fix:`, `test:`, `refactor:`)
|
|
|
|
Weitere Details findest du in [CLAUDE.md](CLAUDE.md).
|