# 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).