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.

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.

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.

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.

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.

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.

// 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.

// 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.

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

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

// 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

// 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

// 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

// ✅ 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

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

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 - Setup und Anpassung
• Beispiele - Praktische Anwendungsfälle
• Migration - Upgrade von älteren Krypto-Implementierungen
• Sicherheit - Detaillierte Sicherheitsrichtlinien