sodium_crypto_kdf_derive_from_key — Funktion · PHP-Referenz

Signatur

sodium_crypto_kdf_derive_from_key(int $subkey_len, int $subkey_id, string $context, string $key): string

Beschreibung

sodium_crypto_kdf_derive_from_key() implementiert eine schlüsselbasierte Schlüsselableitungsfunktion (Key Derivation Function, KDF) auf Basis von BLAKE2b. Aus einem einzigen sicheren Hauptschlüssel lassen sich beliebig viele unabhängige Unterschlüssel erzeugen, ohne dass der Hauptschlüssel selbst je direkt genutzt werden muss.

Jeder abgeleitete Schlüssel ist durch eine numerische ID ($subkey_id) und einen kurzen Kontext-String ($context) eindeutig bestimmt. Zwei Unterschlüssel mit unterschiedlicher ID oder unterschiedlichem Kontext sind kryptographisch voneinander unabhängig — die Kompromittierung eines Unterschlüssels gibt keinerlei Information über andere Unterschlüssel oder den Hauptschlüssel preis.

Typische Anwendungsfälle sind: Ableitung von Schlüsseln für Verschlüsselung, MAC-Bildung oder Authentifizierung aus einem einzigen, sicher gespeicherten Master Key — zum Beispiel für verschiedene Dienste, Nutzer oder Datenkategorien innerhalb einer Anwendung.

Der Hauptschlüssel sollte mit sodium_crypto_kdf_keygen() erzeugt werden und hat eine feste Länge von SODIUM_CRYPTO_KDF_KEYBYTES (32 Bytes).
Der Kontext-String muss exakt 8 Bytes lang sein.
Die Länge des Unterschlüssels muss zwischen SODIUM_CRYPTO_KDF_BYTES_MIN (16) und SODIUM_CRYPTO_KDF_BYTES_MAX (64) liegen.

Parameter

Name	Typ	Beschreibung
$subkey_len Pflicht	int	Gewünschte Länge des abgeleiteten Unterschlüssels in Bytes. Muss zwischen `SODIUM_CRYPTO_KDF_BYTES_MIN` (16) und `SODIUM_CRYPTO_KDF_BYTES_MAX` (64) liegen.
$subkey_id Pflicht	int	Numerische ID des Unterschlüssels. Muss eine nicht-negative ganze Zahl sein. Verschiedene IDs erzeugen völlig unabhängige Unterschlüssel.
$context Pflicht	string	Ein exakt 8 Bytes langer Kontext-String, der den Verwendungszweck des Unterschlüssels identifiziert (z. B. `'auth_key'` oder `'enc_key_'`). Trennt Schlüsselbereiche semantisch.
$key Pflicht	string	Der Hauptschlüssel (Master Key), aus dem der Unterschlüssel abgeleitet wird. Muss exakt `SODIUM_CRYPTO_KDF_KEYBYTES` (32) Bytes lang sein, am besten erzeugt mit `sodium_crypto_kdf_keygen()`.

Rückgabewert

Typ

string

Beschreibung

Gibt den abgeleiteten Unterschlüssel als binären String der Länge $subkey_len zurück. Bei ungültigen Parametern (z. B. falsche Kontextlänge oder Schlüssellänge) wird eine SodiumException ausgeworfen.

Beispiele

Unterschlüssel für Verschlüsselung und Authentifizierung ableiten

<?php
// Master Key einmalig erzeugen und sicher speichern
$masterKey = sodium_crypto_kdf_keygen();

// Kontext muss exakt 8 Bytes lang sein
$contextEnc  = 'enc_key_'; // 8 Zeichen
$contextAuth = 'auth_key'; // 8 Zeichen

// Verschlüsselungsschlüssel für Nutzer-ID 42
$encKey = sodium_crypto_kdf_derive_from_key(
    SODIUM_CRYPTO_SECRETBOX_KEYBYTES, // 32 Bytes
    42,
    $contextEnc,
    $masterKey
);

// Authentifizierungsschlüssel für Nutzer-ID 42
$authKey = sodium_crypto_kdf_derive_from_key(
    SODIUM_CRYPTO_AUTH_KEYBYTES, // 32 Bytes
    42,
    $contextAuth,
    $masterKey
);

echo 'Enc-Key  (hex): ' . sodium_bin2hex($encKey) . PHP_EOL;
echo 'Auth-Key (hex): ' . sodium_bin2hex($authKey) . PHP_EOL;

// Speicher bereinigen
sodium_memzero($masterKey);
sodium_memzero($encKey);
sodium_memzero($authKey);

Enc-Key (hex): <32-Byte-Hex-Wert> Auth-Key (hex): <32-Byte-Hex-Wert>

Mehrere Nutzer-Schlüssel aus einem Master Key ableiten

<?php
$masterKey = sodium_crypto_kdf_keygen();
$context   = 'usr_data'; // exakt 8 Bytes

$userIds = [1, 2, 3];

foreach ($userIds as $userId) {
    $userKey = sodium_crypto_kdf_derive_from_key(
        32,          // Schlüssellänge
        $userId,     // Nutzer-ID als Subkey-ID
        $context,
        $masterKey
    );
    echo "Schlüssel für Nutzer $userId: " . sodium_bin2hex($userKey) . PHP_EOL;
    sodium_memzero($userKey);
}

sodium_memzero($masterKey);

Schlüssel für Nutzer 1: <32-Byte-Hex-Wert> Schlüssel für Nutzer 2: <32-Byte-Hex-Wert> Schlüssel für Nutzer 3: <32-Byte-Hex-Wert>

// Wichtig · Fallstricke

Kontextlänge: Der $context-Parameter muss exakt 8 Bytes lang sein. Kürzere oder längere Strings führen zu einer SodiumException. Gegebenenfalls mit str_pad() auffüllen oder auf 8 Zeichen kürzen — besser jedoch von Anfang an passende Konstanten definieren.

Sicherheit des Master Keys: Der Hauptschlüssel ist der einzige geheime Eingangswert. Er sollte ausschließlich im Arbeitsspeicher vorliegen und niemals persistiert oder geloggt werden. Nach Gebrauch sollte er mit sodium_memzero() überschrieben werden.

Determinismus: Die Funktion ist deterministisch — gleiche Eingaben liefern immer denselben Ausgabe-Schlüssel. Das ist gewollt, um Schlüssel bei Bedarf reproduzieren zu können, ohne sie speichern zu müssen.

Keine Schlüsselrotation: Die KDF ersetzt keine echte Schlüsselrotation. Wird der Master Key kompromittiert, sind alle abgeleiteten Schlüssel ebenfalls kompromittiert.

Siehe auch

sodium_crypto_kdf_keygen sodium_crypto_secretbox_keygen sodium_crypto_pwhash sodium_memzero sodium_bin2hex