michaelschiemer/docs/components/cryptography/index.md

# Cryptography Module

Das Cryptography Module erweitert die bestehenden Verschlüsselungsfunktionen des Frameworks um moderne kryptographische Primitive und bietet sichere Implementierungen für Schlüsselableitung, digitale Signaturen, erweiterte Hash-Funktionen und sichere Token-Generierung.

## Überblick

Das Modul folgt den Framework-Prinzipien:
- **Immutable Value Objects** für sichere Datenrepräsentation
- **Service Pattern** für Business Logic
- **Dependency Injection** für RandomGenerator Integration
- **Security-First Design** mit timing-sicheren Operationen

## Core Services

### KeyDerivationFunction Service

Sichere Schlüsselableitung für Password-Hashing und Key-Stretching.

```php
use App\Framework\Cryptography\KeyDerivationFunction;
use App\Framework\Random\SecureRandomGenerator;

$kdf = new KeyDerivationFunction(new SecureRandomGenerator());

// PBKDF2 (Standard)
$derivedKey = $kdf->pbkdf2('password', $salt, 100000, 32);

// Argon2ID (Empfohlen)
$derivedKey = $kdf->argon2id('password', $salt, 65536, 4, 3, 32);

// Password mit automatischer Salt-Generierung hashen
$derivedKey = $kdf->hashPassword('password', 'argon2id');

// Password verifizieren
$isValid = $kdf->verify('password', $derivedKey);
```

**Unterstützte Algorithmen:**
- **PBKDF2** mit SHA-256, SHA-512, SHA-384, SHA-224
- **Argon2ID** (empfohlen für neue Implementierungen)  
- **scrypt** für spezielle Anwendungsfälle

### DigitalSignature Service

Digitale Signaturen für Datenintegrität und Authentifizierung.

```php
use App\Framework\Cryptography\DigitalSignature;

$signature = new DigitalSignature(new SecureRandomGenerator());

// RSA Schlüsselpaar generieren
$keyPair = $signature->generateRsaKeyPair(2048);

// Daten signieren
$signatureResult = $signature->sign('data to sign', $keyPair->getPrivateKey());

// Signatur verifizieren
$isValid = $signature->verify('data to sign', $signatureResult, $keyPair->getPublicKey());

// ECDSA mit secp256r1
$ecKeyPair = $signature->generateEcdsaKeyPair('secp256r1');
$ecSignature = $signature->signWithEcdsa('data', $ecKeyPair->getPrivateKey());
```

### AdvancedHash Service  

Erweiterte Hash-Funktionen über grundlegende Algorithmen hinaus.

```php
use App\Framework\Cryptography\AdvancedHash;

$hash = new AdvancedHash();

// SHA-3 Familie
$sha3 = $hash->sha3('data', 256);
$shake = $hash->shake('data', 32, 128); // Extendable-output function

// BLAKE2
$blake2b = $hash->blake2b('data', 32, 'optional-key');
$blake2s = $hash->blake2s('data', 16);

// Hash-Ketten für komplexe Szenarien  
$chainResult = $hash->hashChain('data', ['sha3-256', 'blake2b']);
```

### SecureTokenGenerator Service

Kryptographisch sichere Token-Generierung für APIs, Sessions und mehr.

```php
use App\Framework\Cryptography\SecureTokenGenerator;

$generator = new SecureTokenGenerator(new SecureRandomGenerator());

// API Keys mit Prefix
$apiKey = $generator->generateApiKey('myapp'); // myapp_...

// Session Tokens
$sessionToken = $generator->generateSessionToken();

// CSRF Tokens
$csrfToken = $generator->generateCsrfToken();

// OTP Tokens
$otp = $generator->generateOtpToken(6); // 6-stelliger numerischer Code

// Custom Tokens mit eigenem Alphabet
$customToken = $generator->generateCustom('0123456789ABCDEF', 16);

// Batch-Generierung
$tokens = $generator->generateBatch('session', 10, 32);
```

**Token-Formate:**
- `FORMAT_BASE64_URL` (Standard, URL-sicher)
- `FORMAT_BASE64` (Standard Base64)
- `FORMAT_HEX` (Hexadezimal)
- `FORMAT_BASE32` (Base32)
- `FORMAT_ALPHANUMERIC` (Buchstaben + Zahlen)

### CryptographicUtilities Service

Sammlung kryptographischer Utility-Funktionen.

```php
use App\Framework\Cryptography\CryptographicUtilities;

$utils = new CryptographicUtilities(new SecureRandomGenerator());

// Timing-sichere String-Vergleiche
$isEqual = $utils->timingSafeEquals($string1, $string2);

// Entropie-Validierung
$isHighEntropy = $utils->validateEntropy($data, 7.0);
$entropy = $utils->calculateShannonEntropy($data);

// Sichere UUIDs
$uuid4 = $utils->generateUuid4(); // Zufällige UUID
$uuid5 = $utils->generateUuid5($namespace, 'name'); // Deterministische UUID

// Key-Stretching
$stretched = $utils->stretchKey('password', 'salt', 10000, 32);

// Speicher sicher löschen
$utils->secureWipe($sensitiveData);
```

## Value Objects

### DerivedKey

Unveränderliche Repräsentation abgeleiteter Schlüssel.

```php
// Eigenschaften abrufen
$algorithm = $derivedKey->getAlgorithm(); // 'pbkdf2-sha256'
$keyLength = $derivedKey->getKeyLength(); // 32
$iterations = $derivedKey->getIterations(); // 100000

// Verschiedene Formate
$hex = $derivedKey->toHex();
$base64 = $derivedKey->toBase64();

// Serialisierung
$array = $derivedKey->toArray();
$restored = DerivedKey::fromArray($array);

// Gleichheit prüfen (timing-sicher)
$isEqual = $derivedKey->equals($otherKey);
```

### SecureToken

Token mit Metadaten und sicherheitsfokussierten Funktionen.

```php
// Token-Eigenschaften
$type = $token->getType(); // 'api_key'
$format = $token->getFormat(); // 'base64_url'
$hasPrefix = $token->hasPrefix(); // true/false

// Sichere Operationen
$isEqual = $token->equals($otherToken); // timing-sicher
$isValid = $token->verify($candidateToken); // timing-sicher

// Sicherheit und Logging
$masked = $token->getMaskedValue(); // myap****_Ab...fG
$fingerprint = $token->getFingerprint(); // SHA-256 Hash
$safeSummary = $token->getSafeSummary(); // Ohne Token-Wert
```

### KeyPair, PrivateKey, PublicKey

Sichere Verwaltung asymmetrischer Schlüssel.

```php
$keyPair = $signature->generateRsaKeyPair(2048);

$privateKey = $keyPair->getPrivateKey();
$publicKey = $keyPair->getPublicKey();

// Schlüssel-Export
$privatePem = $privateKey->toPem();
$publicPem = $publicKey->toPem();

// Schlüssel-Import  
$privateKey = PrivateKey::fromPem($privatePem);
$publicKey = PublicKey::fromPem($publicPem);
```

## Sicherheitsfeatures

### Timing-Attack Schutz

Alle kritischen Vergleichsoperationen verwenden timing-sichere Implementierungen:

```php
// Timing-sichere String-Vergleiche
$utils->timingSafeEquals($secret1, $secret2);

// Timing-sichere Token-Verifikation  
$token->verify($candidateToken);

// Timing-sichere Array-Suche
$utils->constantTimeArraySearch($haystack, $needle);
```

### Entropie-Validierung

Automatische Validierung der Schlüsselstärke:

```php
// Shannon-Entropie berechnen
$entropy = $utils->calculateShannonEntropy($data);

// Mindest-Entropie validieren
$isStrong = $utils->validateEntropy($data, 7.0);

// Schlüsselstärke prüfen
$isValidKey = $utils->validateKeyStrength($key, 128); // Minimum 128 Bits
```

### Sichere Speicher-Verwaltung

```php
// Sensitive Daten sicher löschen
$utils->secureWipe($password); // Überschreibt Speicher

// Automatische Metadaten-Bereinigung in Token-Logs
$safeSummary = $token->getSafeSummary(); // Ohne sensitive Werte
```

## Best Practices

### Empfohlene Parameter

```php
// PBKDF2 (Minimum)
$kdf->pbkdf2($password, $salt, 100000, 32, 'sha256');

// Argon2ID (Empfohlen)
$kdf->argon2id($password, $salt, 65536, 4, 3, 32);

// RSA Schlüssel (Minimum 2048 Bit)
$signature->generateRsaKeyPair(2048);

// Token-Längen
$generator->generateApiKey('prefix', 32); // 256 Bit
$generator->generateSessionToken(48);     // 384 Bit für langlebige Sessions
```

### Sichere Implementierung

```php
// ✅ Gute Praxis
final readonly class AuthService  
{
    public function __construct(
        private readonly KeyDerivationFunction $kdf,
        private readonly SecureTokenGenerator $tokenGenerator
    ) {}
    
    public function hashPassword(string $password): DerivedKey
    {
        return $this->kdf->hashPassword($password, 'argon2id');
    }
    
    public function generateApiKey(string $prefix): SecureToken
    {
        return $this->tokenGenerator->generateApiKey($prefix, 32);
    }
}

// ❌ Schlechte Praxis - Nicht verwenden
// $hashedPassword = md5($password); // Unsicher
// $token = bin2hex(random_bytes(16)); // Zu kurz, keine Metadaten
```

## Integration mit Framework

### Dependency Injection

```php
final readonly class CryptographyServiceInitializer implements Initializer
{
    public function initialize(Container $container): void
    {
        $randomGenerator = $container->get(RandomGenerator::class);
        
        $container->singleton(KeyDerivationFunction::class, 
            new KeyDerivationFunction($randomGenerator));
        
        $container->singleton(SecureTokenGenerator::class,
            new SecureTokenGenerator($randomGenerator));
            
        $container->singleton(CryptographicUtilities::class,
            new CryptographicUtilities($randomGenerator));
    }
}
```

### Controller Integration

```php
final readonly class ApiKeyController
{
    #[Route(path: '/admin/api-keys', method: Method::POST)]
    #[Auth(strategy: 'ip', allowedIps: ['127.0.0.1'])]
    public function createApiKey(
        CreateApiKeyRequest $request,
        SecureTokenGenerator $tokenGenerator
    ): JsonResult {
        $apiKey = $tokenGenerator->generateApiKey(
            prefix: $request->prefix,
            length: 32
        );
        
        // Token sicher in Datenbank speichern
        // Nur Hash oder verschlüsselte Version speichern, nie Klartext
        
        return new JsonResult([
            'api_key' => $apiKey->getValue(),
            'fingerprint' => $apiKey->getShortFingerprint(),
            'created_at' => $apiKey->getCreatedAt()->format('c')
        ]);
    }
}
```

## Performance

Das Cryptography Module ist für Production-Einsatz optimiert:

- **Cached Reflection Provider** für Dependency Injection
- **Batch-Operationen** für Token-Generierung
- **Effiziente Algorithmen** mit modernen kryptographischen Standards
- **Minimale Speicher-Allokation** durch readonly Value Objects

## Weiterführende Dokumentation

- [Konfiguration](configuration.md) - Setup und Anpassung
- [Beispiele](examples.md) - Praktische Anwendungsfälle  
- [Migration](migration.md) - Upgrade von älteren Krypto-Implementierungen
- [Sicherheit](security.md) - Detaillierte Sicherheitsrichtlinien