Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
365
docs/components/cryptography/index.md
Normal file
365
docs/components/cryptography/index.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user