用 PHP 解密密钥库文件:以太坊、BNB、Polygon
如何用 PHP 解密以太坊密钥库(Web3 Secret Storage v3)JSON 文件,包含经测试的 PBKDF2 示例、MAC 校验步骤和常见错误排查。同时说明为何应在离线机器上解密,以及如何离线使用免费的 Keystore Decryptor 工具。
审核: Maurice Sobiera
密钥库文件是一个 JSON 文件,依据 Web3 Secret Storage Definition 第 3 版,用密码加密保存以太坊格式的私钥。以太坊、BNB 智能链和 Polygon 均使用该格式。解密步骤为:从密码派生密钥,校验 MAC,再以 AES-128-CTR 解密。
什么是密钥库文件?
密钥库文件让应用可以把私钥保存在磁盘上,而无需以明文形式存储。文件中包含加密后的私钥、从密码派生加密密钥所需的参数,以及一个称为 MAC 的校验值。任何人只要同时拥有该文件和密码,就能恢复私钥,因此两者都应当视为机密。
该格式在 ethereum.org 的 Web3 Secret Storage Definition 中有所描述。同一个文件适用于所有 EVM 网络,因为私钥和地址在这些网络上的派生方式完全相同。
密钥库如何解密?
解密分为规范定义的四个步骤。文件中的 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:对派生密钥的第 16 到 31 字节加上密文后做 Keccak-256 哈希,并将结果与
mac字段比较。 - 若 MAC 相符,则取派生密钥的前 16 字节作为 AES 密钥。
- 使用文件中的
iv,以 AES-128-CTR 解密密文。
MAC 校验可在解密前告诉您密码是否正确。密码错误会派生出不同的密钥,因而得到不同的 MAC。
如何用 PHP 解密密钥库文件?
PBKDF2 使用 hash_pbkdf2(),AES 使用 openssl_decrypt(),MAC 则需要一个 Keccak-256 库。PHP 内置的 hash('sha3-256') 是 NIST 的 SHA-3 函数,结果与 Keccak-256 不同。使用 Composer 安装这个纯 PHP 库:
composer require kornrunner/keccakscrypt 密钥库还需要 php-scrypt 扩展,可用 pecl install scrypt 安装。PBKDF2 密钥库则不需要它。大多数 PHP 版本都已启用 openssl 扩展。
<?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;派生密钥以十六进制字符串保存,因此每个字节占两个字符。这就是密钥取 substr($derivedKey, 0, 32)、MAC 部分从第 32 个字符开始的原因。
代码能通过已知测试向量吗?
PBKDF2 可以。规范中包含一个 PBKDF2 测试向量,密码为 testpassword。我们用该代码的 PBKDF2 分支运行了这一测试,输出的私钥为规范中给出的 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d。使用错误密码再次运行时,程序会在 MAC 校验处停止。我们没有在 PHP 中测试 scrypt 分支,因此在依赖它之前,请用您已知私钥的密钥库进行测试。
MAC 校验为什么会失败?
MAC 不匹配通常有四个常见原因:
- 密码错误。这是最可能的原因。
- 使用的是 NIST SHA3-256 而非 Keccak-256。某些库把两者都称为 SHA-3,但它们的填充方式不同,输出也不同。
- 派生密钥的切分位置有误。MAC 使用第 16 到 31 字节,加密密钥使用第 0 到 15 字节。
- 盐值被当作文本使用,而不是先从十六进制解码。
当 n 为 262144、r 为 8 时,scrypt 密钥库的派生需要约 256 MiB 内存,因为 RFC 7914 给出的内存用量约为 128 × N × r 字节。在小型服务器上,这可能失败,或需要数秒才能完成。
在联网的机器上解密密钥库安全吗?
不安全,应避免。私钥一旦输出,该机器上的任何恶意软件、日志文件或 Shell 历史记录都可能捕获它。请在离线的机器上解密,事后清除终端历史,并且不要把私钥或密钥库粘贴到您无法控制的网站中。
我们还在 GitHub 上提供一个免费的 Keystore Decryptor。其 README 说明,它完全在浏览器中运行,基于 keythereum 库,且从不向服务器发送数据。若要离线使用,请克隆仓库、断开网络连接,然后打开 index.html。在使用任何处理私钥的工具之前,请先阅读其源代码。关于密钥管理的一般建议,请参阅我们的安全建议。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。