From f456538b11ca49a96db36ac74698c11bca050900 Mon Sep 17 00:00:00 2001
From: Joachim Hummel <jh@unixweb.de>
Date: Thu, 13 Nov 2025 20:08:05 +0000
Subject: [PATCH] docs: add README.md for repository
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 README.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2628f07
--- /dev/null
+++ b/README.md
@@ -0,0 +1,163 @@
+# 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).