sodium_crypto_kdf_keygen — Funktion · PHP-Referenz

Signatur

sodium_crypto_kdf_keygen(): string

Beschreibung

sodium_crypto_kdf_keygen() erzeugt einen zufälligen Stammschlüssel (master key) der festen Länge SODIUM_CRYPTO_KDF_KEYBYTES (32 Byte), der als Basis für die Ableitung von Unterschlüsseln mittels sodium_crypto_kdf_derive_from_key() dient. Der Stammschlüssel selbst wird dabei nie direkt zur Verschlüsselung verwendet.

Das Konzept hinter einer KDF (Key Derivation Function) erlaubt es, aus einem einzigen sicher gespeicherten Stammschlüssel beliebig viele Unterschlüssel für verschiedene Zwecke abzuleiten – zum Beispiel je einen Schlüssel pro Nutzer, pro Datei oder pro Dienst. So muss nur ein einziger Schlüssel sicher aufbewahrt werden.

Die erzeugte Zufallsfolge basiert auf dem kryptografisch sicheren Zufallsgenerator des Betriebssystems und ist direkt einsatzbereit. Der Rückgabewert sollte sicher gespeichert werden, beispielsweise in einer Umgebungsvariablen, einem Secrets-Manager oder einem Hardware-Sicherheitsmodul.

Diese Funktion ist Teil der Libsodium-Erweiterung, die seit PHP 7.2 als Core-Extension enthalten ist und auf der bewährten BLAKE2b-basierten KDF von NaCl/libsodium aufbaut.

Rückgabewert

Typ

string

Beschreibung

Gibt einen binären String der Länge SODIUM_CRYPTO_KDF_KEYBYTES (32 Byte) zurück, der den zufällig generierten Stammschlüssel enthält.

Beispiele

Stammschlüssel erzeugen und Unterschlüssel ableiten

<?php
// Stammschlüssel erzeugen (einmalig, sicher speichern!)
$masterKey = sodium_crypto_kdf_keygen();

// Kontextstring: genau 8 Byte, beschreibt den Verwendungszweck
$context = 'MyAppV1';

// Zwei verschiedene Unterschlüssel mit unterschiedlichen IDs ableiten
$subKey1 = sodium_crypto_kdf_derive_from_key(32, 1, $context, $masterKey);
$subKey2 = sodium_crypto_kdf_derive_from_key(32, 2, $context, $masterKey);

echo 'Stammschlüssel (hex): ' . sodium_bin2hex($masterKey) . PHP_EOL;
echo 'Unterschlüssel 1 (hex): ' . sodium_bin2hex($subKey1) . PHP_EOL;
echo 'Unterschlüssel 2 (hex): ' . sodium_bin2hex($subKey2) . PHP_EOL;

// Speicher für sensible Schlüssel bereinigen
sodium_memzero($masterKey);
sodium_memzero($subKey1);
sodium_memzero($subKey2);

Stammschlüssel (hex): <32 zufällige Bytes als Hex> Unterschlüssel 1 (hex): <abgeleitete 32 Bytes als Hex> Unterschlüssel 2 (hex): <abgeleitete 32 Bytes als Hex>

Stammschlüssel sicher in .env speichern und laden

<?php
// Einmalige Erzeugung und Ausgabe zur sicheren Speicherung (z. B. in .env)
$masterKey = sodium_crypto_kdf_keygen();
$encoded = sodium_bin2hex($masterKey);
sodium_memzero($masterKey);

echo 'APP_MASTER_KEY=' . $encoded . PHP_EOL;
// Diesen Wert sicher als Umgebungsvariable setzen, nicht in Code committen!

// ---
// Später beim Laden aus der Umgebungsvariablen:
$loadedKey = sodium_hex2bin(getenv('APP_MASTER_KEY'));

$subKey = sodium_crypto_kdf_derive_from_key(32, 1, 'AuthTokn', $loadedKey);
echo 'Auth-Token-Schlüssel (hex): ' . sodium_bin2hex($subKey) . PHP_EOL;

sodium_memzero($loadedKey);
sodium_memzero($subKey);

APP_MASTER_KEY: <64 Hex-Zeichen> Auth-Token-Schlüssel (hex): <64 Hex-Zeichen>

// Wichtig · Fallstricke

Sicherheitshinweise:

Der Stammschlüssel ist hochsensibel – er darf niemals im Quellcode, in Logs oder in der Datenbank im Klartext gespeichert werden.
Verwende nach der Nutzung stets sodium_memzero(), um den Schlüssel aus dem Speicher zu löschen und ihn vor möglichen Memory-Dumps zu schützen.
Der Kontextstring bei sodium_crypto_kdf_derive_from_key() muss exakt 8 Byte lang sein – andernfalls wird eine Exception geworfen.
Eine KDF ist kein Ersatz für eine ordentliche Schlüsselverwaltung (Key Management System). Für Produktionsumgebungen empfehlen sich dedizierte Secrets-Manager (z. B. HashiCorp Vault, AWS Secrets Manager).
Die Funktion wirft eine SodiumException, wenn die Libsodium-Erweiterung nicht korrekt initialisiert werden kann.

Siehe auch

sodium_crypto_kdf_derive_from_key sodium_memzero sodium_bin2hex sodium_hex2bin sodium_crypto_secretbox_keygen sodium_crypto_generichash_keygen