sodium_crypto_kx_secretkey — Funktion · PHP-Referenz

Signatur

sodium_crypto_kx_secretkey(string $keypair): string

Beschreibung

sodium_crypto_kx_secretkey() entnimmt einem kombinierten crypto_kx-Schlüsselpaar den privaten (geheimen) Anteil und gibt ihn als rohen Binär-String zurück. Das Schlüsselpaar selbst enthält beide Teile – öffentlichen und geheimen Schlüssel – in einer einzelnen Zeichenkette kodiert.

Die Funktion ist Teil des Schlüsselaustausch-Protokolls (Key Exchange, KX) der libsodium-Bibliothek, das auf dem X25519-Verfahren basiert. Mit dem geheimen Schlüssel lassen sich im Anschluss gemeinsame Sitzungsschlüssel ableiten, etwa mit sodium_crypto_kx_client_session_keys() oder sodium_crypto_kx_server_session_keys().

Typischerweise wird der geheime Schlüssel niemals direkt übertragen oder gespeichert, sondern ausschließlich lokal gehalten. Er ermöglicht es, aus dem öffentlichen Schlüssel der Gegenseite ein gemeinsames Geheimnis zu berechnen, ohne dieses jemals explizit auszutauschen.

Beim persistenten Speichern des Schlüssels empfiehlt es sich, den geheimen Schlüssel verschlüsselt abzulegen, zum Beispiel mit sodium_crypto_secretbox() oder einem passwortbasierten Schlüsselableitungsverfahren wie sodium_crypto_pwhash().

Parameter

Name	Typ	Default	Beschreibung
$keypair Pflicht	string		Ein vollständiges crypto_kx-Schlüsselpaar als Binär-String, erzeugt von `sodium_crypto_kx_keypair()` oder `sodium_crypto_kx_seed_keypair()`. Die Länge muss exakt `SODIUM_CRYPTO_KX_KEYPAIRBYTES` Bytes betragen.

Rückgabewert

Typ

string

Beschreibung

Gibt den geheimen Schlüssel als rohen Binär-String der Länge SODIUM_CRYPTO_KX_SECRETKEYBYTES (32 Bytes) zurück.

Beispiele

Geheimen Schlüssel aus einem zufällig generierten Schlüsselpaar extrahieren

<?php
// Zufälliges Schlüsselpaar erzeugen
$keypair = sodium_crypto_kx_keypair();

// Geheimen Schlüssel extrahieren
$secretKey = sodium_crypto_kx_secretkey($keypair);

// Öffentlichen Schlüssel extrahieren (zum Vergleich)
$publicKey = sodium_crypto_kx_publickey($keypair);

echo 'Länge des geheimen Schlüssels: ' . strlen($secretKey) . ' Bytes' . PHP_EOL;
echo 'Länge des öffentlichen Schlüssels: ' . strlen($publicKey) . ' Bytes' . PHP_EOL;
echo 'Geheimer Schlüssel (hex): ' . sodium_bin2hex($secretKey) . PHP_EOL;

// Speicher nach Benutzung bereinigen
sodium_memzero($secretKey);

Länge des geheimen Schlüssels: 32 Bytes Länge des öffentlichen Schlüssels: 32 Bytes Geheimer Schlüssel (hex): <32-Byte-Zufallswert als Hex>

Schlüsselaustausch zwischen Client und Server

<?php
// --- Client-Seite ---
$clientKeypair = sodium_crypto_kx_keypair();
$clientPublicKey = sodium_crypto_kx_publickey($clientKeypair);
$clientSecretKey = sodium_crypto_kx_secretkey($clientKeypair);

// --- Server-Seite ---
$serverKeypair = sodium_crypto_kx_keypair();
$serverPublicKey = sodium_crypto_kx_publickey($serverKeypair);
$serverSecretKey = sodium_crypto_kx_secretkey($serverKeypair);

// Client berechnet Sitzungsschlüssel mit dem öffentlichen Schlüssel des Servers
[$clientRx, $clientTx] = sodium_crypto_kx_client_session_keys(
    $clientKeypair,
    $serverPublicKey
);

// Server berechnet Sitzungsschlüssel mit dem öffentlichen Schlüssel des Clients
[$serverRx, $serverTx] = sodium_crypto_kx_server_session_keys(
    $serverKeypair,
    $clientPublicKey
);

// Client-TX muss mit Server-RX übereinstimmen (und umgekehrt)
echo 'Schlüssel stimmen überein: ';
echo (sodium_memcmp($clientTx, $serverRx) === 0 ? 'JA' : 'NEIN') . PHP_EOL;

// Geheime Schlüssel aus dem Speicher löschen
sodium_memzero($clientSecretKey);
sodium_memzero($serverSecretKey);

Schlüssel stimmen überein: JA

// Wichtig · Fallstricke

Sicherheitshinweise:

Den geheimen Schlüssel niemals über unsichere Kanäle übertragen oder im Klartext persistieren.
Nach der Verwendung des geheimen Schlüssels im Arbeitsspeicher empfiehlt sich der Einsatz von sodium_memzero(), um den Speicherbereich zu überschreiben und so Speicher-Dump-Angriffe zu erschweren.
Wird das Schlüsselpaar dauerhaft gespeichert (z. B. in einer Datei oder Datenbank), sollte es vor der Ablage mit einem starken Verfahren verschlüsselt werden.
Die Funktion wirft eine SodiumException, wenn $keypair nicht die korrekte Länge von SODIUM_CRYPTO_KX_KEYPAIRBYTES Bytes aufweist.

Siehe auch

sodium_crypto_kx_keypair sodium_crypto_kx_seed_keypair sodium_crypto_kx_publickey sodium_crypto_kx_client_session_keys sodium_crypto_kx_server_session_keys sodium_memzero