Descifrar keystore en PHP: Ethereum, BNB, Polygon
Cómo descifrar en PHP un archivo keystore de Ethereum (Web3 Secret Storage v3), con un ejemplo PBKDF2 probado, comprobación del MAC y errores frecuentes.
Revisado por Maurice Sobiera
Un archivo keystore es un JSON que guarda una clave privada al estilo de Ethereum, cifrada con una contraseña, según la Web3 Secret Storage Definition, versión 3. Ethereum, BNB Smart Chain y Polygon usan todos este formato. Para descifrarlo, derive una clave a partir de la contraseña, compruebe el MAC y descifre el texto cifrado con AES-128-CTR.
¿Qué es un archivo keystore?
Un archivo keystore permite a una aplicación guardar una clave privada en disco sin almacenarla en texto plano. El archivo contiene la clave cifrada, los parámetros necesarios para derivar la clave de cifrado a partir de una contraseña y una suma de control llamada MAC. Quien tenga el archivo y la contraseña puede recuperar la clave privada, así que trate ambos como secretos.
El formato se describe en la Web3 Secret Storage Definition de ethereum.org. El mismo archivo sirve para cualquier red EVM, porque la clave y la dirección se derivan de la misma forma en todas ellas.
¿Cómo funciona el descifrado de un keystore?
El descifrado sigue cuatro pasos que define la especificación. El objeto crypto del archivo contiene todo lo necesario:
| Campo | Significado |
|---|---|
kdf | Función de derivación de clave, pbkdf2 o scrypt |
kdfparams | Parámetros del KDF: salt, dklen y c (PBKDF2) o n, r, p (scrypt) |
cipher | Algoritmo de cifrado, aes-128-ctr en los archivos conformes |
cipherparams.iv | Vector de inicialización del cifrado |
ciphertext | La clave privada cifrada |
mac | Suma de control usada para verificar la contraseña |
Los pasos son:
- Derive una clave a partir de la contraseña con el KDF y sus parámetros. PBKDF2 está especificado en la RFC 8018, y scrypt en la RFC 7914.
- Calcule el MAC como el hash Keccak-256 de los bytes 16 a 31 de la clave derivada seguido del texto cifrado, y compárelo con el campo
mac. - Si el MAC coincide, tome los primeros 16 bytes de la clave derivada como clave AES.
- Descifre el texto cifrado con AES-128-CTR, usando el
ivdel archivo.
La comprobación del MAC le indica si la contraseña era correcta antes de intentar descifrar. Una contraseña errónea da una clave derivada distinta y, por tanto, un MAC distinto.
¿Cómo se descifra un archivo keystore en PHP?
Use hash_pbkdf2() para PBKDF2, openssl_decrypt() para AES y una biblioteca Keccak-256 para el MAC. La función hash('sha3-256') integrada en PHP es la SHA-3 de NIST, que da un resultado distinto de Keccak-256. Instale la biblioteca en PHP puro con Composer:
composer require kornrunner/keccakLos keystores scrypt también necesitan la extensión php-scrypt, que puede instalar con pecl install scrypt. Los keystores PBKDF2 no la necesitan. La extensión openssl está habilitada en la mayoría de las compilaciones de 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;La clave derivada se guarda como cadena hexadecimal, así que cada byte ocupa dos caracteres. Por eso la clave es substr($derivedKey, 0, 32) y la parte del MAC empieza en el carácter 32.
¿El código funciona con un vector de prueba conocido?
Sí, para PBKDF2. La especificación contiene un vector de prueba PBKDF2 con la contraseña testpassword. Ejecutamos la rama PBKDF2 de este código contra él, y devolvió el secreto 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d indicado en la especificación. La misma ejecución con una contraseña incorrecta se detiene en la comprobación del MAC. No probamos la rama scrypt en PHP, así que ejecútela contra un keystore cuya clave ya conozca antes de confiar en ella.
¿Por qué falla la comprobación del MAC?
Un MAC que no coincide tiene cuatro causas habituales:
- La contraseña es incorrecta. Es la causa más probable.
- La función hash es SHA3-256 de NIST en lugar de Keccak-256. Ambas se llaman SHA-3 en algunas bibliotecas, pero difieren en el relleno y producen salidas distintas.
- La clave derivada se cortó en el lugar equivocado. El MAC usa los bytes 16 a 31, y la clave de cifrado usa los bytes 0 a 15.
- La sal se usó como texto en lugar de decodificarla desde hexadecimal.
Un keystore scrypt con n de 262144 y r de 8 necesita unos 256 MiB de memoria para la derivación, ya que la RFC 7914 indica que el uso de memoria es aproximadamente 128 × N × r bytes. En un servidor pequeño esto puede fallar o tardar varios segundos.
¿Es seguro descifrar un keystore en un equipo conectado?
Evítelo. Una vez impresa la clave privada, cualquier malware, archivo de registro o historial de shell de esa máquina puede capturarla. Descifre en un equipo sin conexión, borre después el historial de la terminal y no pegue una clave ni un keystore en un sitio web que no controle.
También publicamos una herramienta Keystore Decryptor gratuita en GitHub. Su README indica que funciona por completo en su navegador, basada en la biblioteca keythereum, y que nunca envía datos a un servidor. Para usarla sin conexión, clone el repositorio, desconéctese de la red y abra index.html. Lea el código fuente antes de usar cualquier herramienta que maneje claves. Para consejos generales sobre el manejo de claves, consulte nuestros consejos de seguridad.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.