Keystore-Datei in PHP entschlüsseln: Ethereum, BNB, Polygon
So entschlüsseln Sie eine Ethereum-Keystore-Datei (Web3 Secret Storage v3) in PHP, mit getestetem PBKDF2-Beispiel, MAC-Prüfung und häufigen Fehlern.
Geprüft von Maurice Sobiera
Eine Keystore-Datei ist eine JSON-Datei, die einen privaten Schlüssel im Ethereum-Stil mit einem Passwort verschlüsselt speichert, wie in der Web3 Secret Storage Definition, Version 3, festgelegt. Ethereum, BNB Smart Chain und Polygon nutzen alle dieses Format. Zum Entschlüsseln leiten Sie aus dem Passwort einen Schlüssel ab, prüfen den MAC und entschlüsseln den Ciphertext mit AES-128-CTR.
Was ist eine Keystore-Datei?
Mit einer Keystore-Datei kann eine Anwendung einen privaten Schlüssel auf der Festplatte halten, ohne ihn im Klartext zu speichern. Die Datei enthält den verschlüsselten Schlüssel, die Parameter, mit denen sich aus einem Passwort der Verschlüsselungsschlüssel ableiten lässt, und eine Prüfsumme namens MAC. Wer die Datei und das Passwort hat, kann den privaten Schlüssel wiederherstellen, behandeln Sie beides daher als Geheimnisse.
Das Format wird in der Web3 Secret Storage Definition auf ethereum.org beschrieben. Dieselbe Datei funktioniert für jedes EVM-Netzwerk, weil Schlüssel und Adresse auf allen auf dieselbe Weise abgeleitet werden.
Wie funktioniert die Entschlüsselung eines Keystores?
Die Entschlüsselung folgt vier Schritten, die die Spezifikation festlegt. Das Objekt crypto der Datei enthält alles, was Sie brauchen:
| Feld | Bedeutung |
|---|---|
kdf | Funktion zur Schlüsselableitung, pbkdf2 oder scrypt |
kdfparams | KDF-Einstellungen: salt, dklen und c (PBKDF2) oder n, r, p (scrypt) |
cipher | Verschlüsselungsalgorithmus, aes-128-ctr bei konformen Dateien |
cipherparams.iv | Initialisierungsvektor für die Verschlüsselung |
ciphertext | Der verschlüsselte private Schlüssel |
mac | Prüfsumme zur Verifizierung des Passworts |
Die Schritte lauten:
- Leiten Sie mit der KDF und ihren Parametern einen Schlüssel aus dem Passwort ab. PBKDF2 ist in RFC 8018 spezifiziert, scrypt in RFC 7914.
- Berechnen Sie den MAC als Keccak-256-Hash der Bytes 16 bis 31 des abgeleiteten Schlüssels, gefolgt vom Ciphertext, und vergleichen Sie ihn mit dem Feld
mac. - Stimmt der MAC überein, nehmen Sie die ersten 16 Bytes des abgeleiteten Schlüssels als AES-Schlüssel.
- Entschlüsseln Sie den Ciphertext mit AES-128-CTR und dem
ivaus der Datei.
Der MAC-Check sagt Ihnen, ob das Passwort richtig war, bevor Sie versuchen zu entschlüsseln. Ein falsches Passwort ergibt einen anderen abgeleiteten Schlüssel und damit einen anderen MAC.
Wie entschlüsseln Sie eine Keystore-Datei in PHP?
Verwenden Sie hash_pbkdf2() für PBKDF2, openssl_decrypt() für AES und eine Keccak-256-Bibliothek für den MAC. Das in PHP eingebaute hash('sha3-256') ist die NIST-SHA-3-Funktion, die ein anderes Ergebnis liefert als Keccak-256. Installieren Sie die reine PHP-Bibliothek mit Composer:
composer require kornrunner/keccakScrypt-Keystores brauchen zusätzlich die Erweiterung php-scrypt, die Sie mit pecl install scrypt installieren können. PBKDF2-Keystores brauchen sie nicht. Die Erweiterung openssl ist in den meisten PHP-Builds aktiviert.
<?phprequire __DIR__ . '/vendor/autoload.php';
use kornrunner\Keccak;
$keystore = json_decode(file_get_contents('/path/to/keystore-file.json'), true);$password = 'YOUR_PASSWORD';
$crypto = $keystore['crypto'] ?? $keystore['Crypto'];$ciphertext = $crypto['ciphertext'];$iv = $crypto['cipherparams']['iv'];$kdf = $crypto['kdf'];$kdfparams = $crypto['kdfparams'];$mac = $crypto['mac'];$salt = hex2bin($kdfparams['salt']);
if ($crypto['cipher'] !== 'aes-128-ctr') { die('Unsupported cipher: ' . $crypto['cipher']);}
// Step 1: derive the key as a hex stringif ($kdf === 'pbkdf2') { $derivedKey = hash_pbkdf2('sha256', $password, $salt, $kdfparams['c'], $kdfparams['dklen'] * 2, false);} elseif ($kdf === 'scrypt') { // php-scrypt returns the derived key as a hex string $derivedKey = scrypt($password, $salt, $kdfparams['n'], $kdfparams['r'], $kdfparams['p'], $kdfparams['dklen']);} else { die('Unsupported KDF: ' . $kdf);}
// Step 2: MAC = Keccak-256(DK[16..31] ++ ciphertext), not NIST SHA3-256$macBody = hex2bin(substr($derivedKey, 32, 32)) . hex2bin($ciphertext);$calculatedMac = Keccak::hash($macBody, 256);
if (!hash_equals(strtolower($mac), $calculatedMac)) { die('MAC mismatch: wrong password or corrupted keystore.');}
// Steps 3 and 4: AES-128-CTR with the first 16 bytes of the derived key$privateKey = openssl_decrypt( hex2bin($ciphertext), 'aes-128-ctr', hex2bin(substr($derivedKey, 0, 32)), OPENSSL_RAW_DATA, hex2bin($iv));
if ($privateKey === false) { die('Decryption failed.');}
echo bin2hex($privateKey), PHP_EOL;Der abgeleitete Schlüssel liegt als Hex-String vor, daher belegt jedes Byte zwei Zeichen. Deshalb lautet der Schlüssel substr($derivedKey, 0, 32), und der MAC-Teil beginnt bei Zeichen 32.
Funktioniert der Code mit einem bekannten Testvektor?
Für PBKDF2 ja. Die Spezifikation enthält einen PBKDF2-Testvektor mit dem Passwort testpassword. Wir haben den PBKDF2-Zweig dieses Codes dagegen laufen lassen, und er gab das in der Spezifikation genannte Secret 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d aus. Derselbe Lauf mit falschem Passwort bricht beim MAC-Check ab. Den scrypt-Zweig haben wir in PHP nicht getestet. Führen Sie ihn daher gegen einen Keystore aus, dessen Schlüssel Sie bereits kennen, bevor Sie sich darauf verlassen.
Warum schlägt der MAC-Check fehl?
Ein MAC-Fehler hat vier häufige Ursachen:
- Das Passwort ist falsch. Das ist die wahrscheinlichste Ursache.
- Die Hashfunktion ist NIST-SHA3-256 statt Keccak-256. In manchen Bibliotheken heißen beide SHA-3, aber sie unterscheiden sich beim Padding und liefern unterschiedliche Ausgaben.
- Der abgeleitete Schlüssel wurde an der falschen Stelle abgeschnitten. Der MAC nutzt die Bytes 16 bis 31, der Cipher-Schlüssel die Bytes 0 bis 15.
- Der Salt wurde als Text verwendet, statt aus Hex dekodiert zu werden.
Ein scrypt-Keystore mit n von 262144 und r von 8 braucht für die Ableitung etwa 256 MiB Arbeitsspeicher, da RFC 7914 den Speicherbedarf mit ungefähr 128 × N × r Bytes angibt. Auf einem kleinen Server kann das scheitern oder mehrere Sekunden dauern.
Ist es sicher, einen Keystore auf einem vernetzten Rechner zu entschlüsseln?
Vermeiden Sie es. Sobald der private Schlüssel ausgegeben ist, kann ihn jede Schadsoftware, jede Logdatei und jede Shell-History auf diesem Rechner erfassen. Entschlüsseln Sie auf einem Rechner ohne Netzverbindung, löschen Sie danach den Terminalverlauf, und fügen Sie keinen Schlüssel und keinen Keystore in eine Website ein, die Sie nicht kontrollieren.
Wir veröffentlichen außerdem einen kostenlosen Keystore Decryptor auf GitHub. Laut README läuft er vollständig in Ihrem Browser, basiert auf der Bibliothek keythereum und sendet nie Daten an einen Server. Um ihn offline zu nutzen, klonen Sie das Repository, trennen die Netzwerkverbindung und öffnen index.html. Lesen Sie den Quellcode, bevor Sie ein Werkzeug verwenden, das Schlüssel verarbeitet. Allgemeine Hinweise zum Umgang mit Schlüsseln finden Sie in unseren Sicherheitstipps.
Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.