← 博客
10 分钟阅读
|
发布于
|
更新于

用 PHP 解密密钥库文件:以太坊、BNB、Polygon

如何用 PHP 解密以太坊密钥库(Web3 Secret Storage v3)JSON 文件,包含经测试的 PBKDF2 示例、MAC 校验步骤和常见错误排查。同时说明为何应在离线机器上解密,以及如何离线使用免费的 Keystore Decryptor 工具。

章节
C
Chaingateway Team
区块链专家

审核: 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
kdfparamsKDF 参数: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:对派生密钥的第 16 到 31 字节加上密文后做 Keccak-256 哈希,并将结果与 mac 字段比较。
  3. 若 MAC 相符,则取派生密钥的前 16 字节作为 AES 密钥。
  4. 使用文件中的 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 库:

Terminal window
composer require kornrunner/keccak

scrypt 密钥库还需要 php-scrypt 扩展,可用 pecl install scrypt 安装。PBKDF2 密钥库则不需要它。大多数 PHP 版本都已启用 openssl 扩展。

<?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;

派生密钥以十六进制字符串保存,因此每个字节占两个字符。这就是密钥取 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 参考。

C
Chaingateway Team
区块链专家

Chaingateway 团队致力于为全球开发者简化区块链集成。