sodium_crypto_kx_keypair — Funktion · PHP-Referenz

Signatur

sodium_crypto_kx_keypair(): string

Beschreibung

sodium_crypto_kx_keypair() generiert ein neues, kryptografisch sicheres Schlüsselpaar für das Sodium-Key-Exchange-Protokoll. Das zurückgegebene Schlüsselpaar wird intern als ein einziger String gespeichert, der sowohl den privaten als auch den öffentlichen Schlüssel enthält. Mit den Hilfsfunktionen sodium_crypto_kx_secretkey() und sodium_crypto_kx_publickey() können die beiden Anteile extrahiert werden.

Das Key-Exchange-Protokoll (basierend auf X25519) ermöglicht es zwei Parteien, gemeinsame Sitzungsschlüssel auszuhandeln, ohne einen gemeinsamen Schlüssel im Voraus festzulegen. Die ausgehandelten Sitzungsschlüssel werden anschließend für die symmetrische Verschlüsselung oder Authentifizierung verwendet.

Typischer Einsatz: Client und Server erzeugen jeweils ein Schlüsselpaar. Danach tauschen sie ihre öffentlichen Schlüssel aus und leiten mit sodium_crypto_kx_client_session_keys() bzw. sodium_crypto_kx_server_session_keys() gemeinsame Sitzungsschlüssel ab. Die privaten Schlüssel verlassen dabei niemals die jeweilige Seite.

Wichtig: Das erzeugte Schlüsselpaar sollte sicher gespeichert werden. Der private Schlüssel darf niemals übertragen werden. Bei einmaligen Sitzungen genügt ein ephemeres Schlüsselpaar; bei langlebigen Identitäten sollte das Schlüsselpaar persistent gespeichert und geheim gehalten werden.

Rückgabewert

Typ

string

Beschreibung

Gibt einen binären String zurück, der sowohl den privaten als auch den öffentlichen Schlüssel enthält. Die Länge beträgt SODIUM_CRYPTO_KX_KEYPAIRBYTES Bytes (64 Bytes). Mit sodium_crypto_kx_secretkey() und sodium_crypto_kx_publickey() können die Einzelbestandteile extrahiert werden.

Beispiele

Schlüsselpaar erzeugen und Teilschlüssel extrahieren

<?php
// Neues Schlüsselpaar für den Key Exchange erzeugen
$keypair = sodium_crypto_kx_keypair();

// Privaten und öffentlichen Schlüssel extrahieren
$secretKey = sodium_crypto_kx_secretkey($keypair);
$publicKey  = sodium_crypto_kx_publickey($keypair);

echo 'Länge des Schlüsselpaars: ' . strlen($keypair) . ' Bytes' . PHP_EOL;
echo 'Länge des privaten Schlüssels: ' . strlen($secretKey) . ' Bytes' . PHP_EOL;
echo 'Länge des öffentlichen Schlüssels: ' . strlen($publicKey) . ' Bytes' . PHP_EOL;

// Öffentlichen Schlüssel base64-kodiert ausgeben (zum Übertragen geeignet)
echo 'Öffentlicher Schlüssel (base64): ' . base64_encode($publicKey) . PHP_EOL;

Länge des Schlüsselpaars: 64 Bytes Länge des privaten Schlüssels: 32 Bytes Länge des öffentlichen Schlüssels: 32 Bytes Öffentlicher Schlüssel (base64): <zufälliger Base64-Wert>

Kompletter Key-Exchange zwischen Client und Server

<?php
// Client erzeugt sein Schlüsselpaar
$clientKeypair = sodium_crypto_kx_keypair();
$clientPublicKey = sodium_crypto_kx_publickey($clientKeypair);

// Server erzeugt sein Schlüsselpaar
$serverKeypair = sodium_crypto_kx_keypair();
$serverPublicKey = sodium_crypto_kx_publickey($serverKeypair);

// Client leitet Sitzungsschlüssel ab (erhält den öffentlichen Schlüssel des Servers)
[$clientRx, $clientTx] = sodium_crypto_kx_client_session_keys($clientKeypair, $serverPublicKey);

// Server leitet Sitzungsschlüssel ab (erhält den öffentlichen Schlüssel des Clients)
[$serverRx, $serverTx] = sodium_crypto_kx_server_session_keys($serverKeypair, $clientPublicKey);

// Prüfen: clientTx muss serverRx entsprechen (und umgekehrt)
if (sodium_memcmp($clientTx, $serverRx) === 0 && sodium_memcmp($clientRx, $serverTx) === 0) {
    echo 'Sitzungsschlüssel stimmen überein – Key Exchange erfolgreich!' . PHP_EOL;
} else {
    echo 'Fehler: Sitzungsschlüssel stimmen NICHT überein!' . PHP_EOL;
}

// Speicher sicher löschen
sodium_memzero($clientKeypair);
sodium_memzero($serverKeypair);

Sitzungsschlüssel stimmen überein – Key Exchange erfolgreich!

// Wichtig · Fallstricke

Sicherheitshinweis: Der private Schlüssel (sodium_crypto_kx_secretkey()) darf niemals übertragen oder geloggt werden. Nur der öffentliche Schlüssel wird ausgetauscht.

Nach der Verwendung sollten sensible Schlüsselmaterialien mit sodium_memzero() aus dem Speicher gelöscht werden, um den Angriffspuffer zu minimieren.

Das Schlüsselpaar basiert auf der Kurve X25519 (Curve25519). Die konstante SODIUM_CRYPTO_KX_KEYPAIRBYTES gibt die Gesamtlänge des Schlüsselpaars an (64 Bytes), SODIUM_CRYPTO_KX_SECRETKEYBYTES und SODIUM_CRYPTO_KX_PUBLICKEYBYTES jeweils 32 Bytes.

Die Funktion ist seit PHP 7.2 verfügbar, da die libsodium-Extension (ext/sodium) ab dieser Version in den PHP-Core integriert wurde. Für ältere PHP-Versionen kann die PECL-Extension libsodium verwendet werden.

Siehe auch

sodium_crypto_kx_secretkey sodium_crypto_kx_publickey sodium_crypto_kx_client_session_keys sodium_crypto_kx_server_session_keys sodium_crypto_kx_seed_keypair sodium_memzero sodium_memcmp