Расшифровка keystore-файла в PHP: Ethereum, BNB, Polygon
Как расшифровать keystore Ethereum (Web3 Secret Storage v3) на PHP: пример с PBKDF2, проверка MAC, проверенный тестовый вектор и частые ошибки.
Проверил(а) Maurice Sobiera
Файл keystore — это JSON-файл, который хранит приватный ключ в формате Ethereum, зашифрованный паролем. Формат описан в Web3 Secret Storage Definition, версия 3. Ethereum, BNB Smart Chain и Polygon используют этот формат. Чтобы расшифровать файл, из пароля выводят ключ, проверяют MAC и расшифровывают шифротекст алгоритмом AES-128-CTR.
Что такое файл keystore?
Файл keystore позволяет приложению хранить приватный ключ на диске, не записывая его открытым текстом. Файл содержит зашифрованный ключ, параметры, необходимые для получения ключа шифрования из пароля, и контрольную сумму, которая называется MAC. Любой, у кого есть файл и пароль, может восстановить приватный ключ, поэтому относитесь к обоим как к секретам.
Формат описан в Web3 Secret Storage Definition на ethereum.org. Один и тот же файл работает во всех EVM-сетях, потому что ключ и адрес выводятся одинаково во всех них.
Как работает расшифровка keystore?
Расшифровка проходит четыре шага, которые определяет спецификация. Объект crypto в файле содержит всё необходимое:
| Поле | Значение |
|---|---|
kdf | Функция получения ключа, pbkdf2 или scrypt |
kdfparams | Параметры KDF: salt, dklen и c (PBKDF2) или n, r, p (scrypt) |
cipher | Алгоритм шифрования, aes-128-ctr для совместимых файлов |
cipherparams.iv | Вектор инициализации для шифра |
ciphertext | Зашифрованный приватный ключ |
mac | Контрольная сумма для проверки пароля |
Шаги:
- Получите ключ из пароля с помощью KDF и его параметров. PBKDF2 описан в RFC 8018, scrypt — в RFC 7914.
- Вычислите MAC как хеш Keccak-256 от байтов 16–31 производного ключа, за которыми следует шифротекст. Сравните результат с полем
mac. - Если MAC совпадает, возьмите первые 16 байт производного ключа как ключ AES.
- Расшифруйте шифротекст алгоритмом AES-128-CTR, используя
ivиз файла.
Проверка MAC показывает, верный ли пароль, до попытки расшифровки. Неверный пароль даёт другой производный ключ, а значит, и другой MAC.
Как расшифровать keystore-файл в PHP?
Используйте hash_pbkdf2() для PBKDF2, openssl_decrypt() для AES и библиотеку Keccak-256 для MAC. Встроенный в PHP hash('sha3-256') — это функция NIST SHA-3, которая даёт другой результат, чем Keccak-256. Установите чистую PHP-библиотеку через Composer:
composer require kornrunner/keccakKeystore со scrypt также требуют расширения php-scrypt, которое ставится командой pecl install scrypt. Keystore с PBKDF2 его не требуют. Расширение openssl включено в большинстве сборок PHP.
<?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;Производный ключ хранится как строка в hex, поэтому каждый байт занимает два символа. Поэтому ключ берётся как substr($derivedKey, 0, 32), а часть для MAC начинается с символа 32.
Работает ли код на известном тестовом векторе?
Да, для PBKDF2. Спецификация содержит тестовый вектор PBKDF2 с паролем testpassword. Мы запустили на нём ветку PBKDF2 этого кода, и она вывела секрет 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d, приведённый в спецификации. Тот же запуск с неверным паролем останавливается на проверке MAC. Ветку scrypt в PHP мы не тестировали. Поэтому запустите её на keystore, ключ которого вам уже известен, прежде чем на неё полагаться.
Почему проверка MAC не проходит?
Несовпадение MAC имеет четыре частые причины:
- Неверный пароль. Это самая вероятная причина.
- Использована функция NIST SHA3-256 вместо Keccak-256. В некоторых библиотеках обе называются SHA-3, но они различаются заполнением (padding) и дают разный результат.
- Производный ключ обрезан не в том месте. MAC использует байты 16–31, а ключ шифра — байты 0–15.
- Соль использовали как текст, а не декодировали из hex.
Keystore со scrypt с n 262144 и r 8 требует около 256 МиБ памяти для вывода ключа. RFC 7914 оценивает использование памяти примерно как 128 × N × r байт. На слабом сервере такой вывод может не сработать или занять несколько секунд.
Безопасно ли расшифровывать keystore на компьютере, подключённом к сети?
Лучше не делать этого. Когда приватный ключ выведен, его может перехватить любое вредоносное ПО, файл журнала или история командной строки на этой машине. Расшифровывайте на машине без подключения к сети, после этого очистите историю терминала и не вставляйте ключ или keystore на сайт, который вы не контролируете.
Мы также публикуем бесплатный Keystore Decryptor на GitHub. Согласно его README, он работает полностью в браузере, основан на библиотеке keythereum и никогда не отправляет данные на сервер. Чтобы использовать его офлайн, клонируйте репозиторий, отключитесь от сети и откройте index.html. Прочитайте исходный код, прежде чем использовать любой инструмент, который работает с ключами. Общие рекомендации по обращению с ключами — в наших советах по безопасности.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.