sodium_crypto_secretbox_keygen — Funktion · PHP-Referenz

Signatur

sodium_crypto_secretbox_keygen(): string

Beschreibung

sodium_crypto_secretbox_keygen() erzeugt einen zufälligen 256-Bit-Schlüssel (32 Bytes), der speziell für die symmetrische, authentifizierte Verschlüsselung mit sodium_crypto_secretbox() und sodium_crypto_secretbox_open() vorgesehen ist. Der Schlüssel wird intern mit einem kryptografisch sicheren Zufallsgenerator (CSPRNG) erzeugt.

Die Funktion ist ein bequemer Helfer, der sicherstellt, dass der erzeugte Schlüssel exakt die von der libsodium-Bibliothek erwartete Länge (SODIUM_CRYPTO_SECRETBOX_KEYBYTES = 32) hat. Eine manuelle Erzeugung mit random_bytes(32) wäre technisch equivalent, diese Funktion macht den Code jedoch ausdrucksstärker und weniger fehleranfällig.

Der zurückgegebene Schlüssel muss sicher gespeichert werden – zum Beispiel in einer Umgebungsvariable, einem Secret-Management-System oder einem sicher konfigurierten Schlüsselspeicher. Er sollte niemals im Klartext in den Quellcode, in Logs oder in die Datenbank geschrieben werden.

Diese Funktion gehört zur libsodium-Erweiterung (ext-sodium), die ab PHP 7.2 Bestandteil des PHP-Kerns ist und den modernen kryptografischen Standard XSalsa20-Poly1305 verwendet.

Rückgabewert

Typ

string

Beschreibung

Ein binärer String mit genau 32 Bytes (SODIUM_CRYPTO_SECRETBOX_KEYBYTES), der einen kryptografisch sicheren Zufallsschlüssel enthält.

Beispiele

Schlüssel erzeugen und eine Nachricht verschlüsseln

<?php
// Schlüssel erzeugen (einmalig, sicher speichern!)
$key = sodium_crypto_secretbox_keygen();
echo 'Schlüssellänge: ' . strlen($key) . ' Bytes' . PHP_EOL;

// Nonce erzeugen (muss für jede Verschlüsselung neu und einzigartig sein)
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);

$plaintext = 'Geheime Nachricht';

// Verschlüsseln
$ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

// Entschlüsseln
$decrypted = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

if ($decrypted === false) {
    throw new RuntimeException('Entschlüsselung fehlgeschlagen – Daten manipuliert oder falscher Schlüssel.');
}

echo 'Entschlüsselt: ' . $decrypted . PHP_EOL;

// Schlüssel sicher aus dem Speicher löschen
sodium_memzero($key);

Schlüssellänge: 32 Bytes Entschlüsselt: Geheime Nachricht

Schlüssel Base64-kodiert persistieren

<?php
// Schlüssel erzeugen
$key = sodium_crypto_secretbox_keygen();

// Für sichere Speicherung Base64-kodieren (z. B. in .env-Datei)
$encodedKey = sodium_bin2base64($key, SODIUM_BASE64_VARIANT_ORIGINAL);
echo 'Schlüssel (Base64): ' . $encodedKey . PHP_EOL;

// Später: Schlüssel aus der Umgebungsvariable laden und dekodieren
// $key = sodium_base642bin($_ENV['SECRET_KEY'], SODIUM_BASE64_VARIANT_ORIGINAL);

// Schlüssel sicher aus dem Speicher entfernen
sodium_memzero($key);

Schlüssel (Base64): <32-Byte-Zufallswert als Base64-String>

// Wichtig · Fallstricke

Sicherheitshinweise:

Speichere den Schlüssel niemals im Quellcode oder in der Datenbank im Klartext. Nutze stattdessen Umgebungsvariablen, Vault-Systeme oder verschlüsselte Konfigurationsspeicher.
Verwende für jede Verschlüsselungsoperation eine einzigartige Nonce (random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES)). Eine Nonce-Wiederverwendung mit demselben Schlüssel kann die Vertraulichkeit vollständig brechen.
Lösche den Schlüssel nach der Verwendung mit sodium_memzero() aus dem Arbeitsspeicher, um das Risiko eines Speicherlecks zu minimieren.
Die Funktion wirft eine SodiumException, wenn die libsodium-Erweiterung nicht verfügbar ist oder intern ein Fehler auftritt.

Siehe auch

sodium_crypto_secretbox sodium_crypto_secretbox_open sodium_memzero sodium_bin2base64 sodium_crypto_aead_xchacha20poly1305_ietf_keygen random_bytes