← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Расшифровка keystore-файла в PHP: Ethereum, BNB, Polygon

Как расшифровать keystore Ethereum (Web3 Secret Storage v3) на PHP: пример с PBKDF2, проверка MAC, проверенный тестовый вектор и частые ошибки.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) 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Контрольная сумма для проверки пароля

Шаги:

  1. Получите ключ из пароля с помощью KDF и его параметров. PBKDF2 описан в RFC 8018, scrypt — в RFC 7914.
  2. Вычислите MAC как хеш Keccak-256 от байтов 16–31 производного ключа, за которыми следует шифротекст. Сравните результат с полем mac.
  3. Если MAC совпадает, возьмите первые 16 байт производного ключа как ключ AES.
  4. Расшифруйте шифротекст алгоритмом 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:

Terminal window
composer require kornrunner/keccak

Keystore со scrypt также требуют расширения php-scrypt, которое ставится командой pecl install scrypt. Keystore с PBKDF2 его не требуют. Расширение openssl включено в большинстве сборок PHP.

<?php
require __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 string
if ($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 блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.