← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

Decifrare un file keystore in PHP: Ethereum, BNB, Polygon

Come decifrare un file keystore Ethereum (Web3 Secret Storage v3) in PHP, con un esempio PBKDF2 testato, il controllo MAC e gli errori più comuni.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Un file keystore è un file JSON che conserva una chiave privata in stile Ethereum cifrata con una password, come definito nella Web3 Secret Storage Definition, versione 3. Ethereum, BNB Smart Chain e Polygon usano tutti questo formato. Per decifrarlo si deriva una chiave dalla password, si verifica il MAC e si decifra il testo cifrato con AES-128-CTR.

Che cos’è un file keystore?

Un file keystore permette a un’applicazione di conservare una chiave privata su disco senza memorizzarla in chiaro. Il file contiene la chiave cifrata, i parametri necessari per derivare la chiave di cifratura dalla password e un checksum chiamato MAC. Chiunque abbia il file e la password può recuperare la chiave privata, quindi trattate entrambi come segreti.

Il formato è descritto nella Web3 Secret Storage Definition su ethereum.org. Lo stesso file funziona su tutte le reti EVM, perché chiave e indirizzo vengono derivati nello stesso modo su tutte.

Come funziona la decifratura del keystore?

La decifratura segue quattro passaggi definiti dalla specifica. L’oggetto crypto del file contiene tutto ciò che serve:

CampoSignificato
kdfFunzione di derivazione della chiave, pbkdf2 o scrypt
kdfparamsImpostazioni della KDF: salt, dklen e c (PBKDF2) oppure n, r, p (scrypt)
cipherAlgoritmo di cifratura, aes-128-ctr per i file conformi
cipherparams.ivVettore di inizializzazione per il cifrario
ciphertextLa chiave privata cifrata
macChecksum usato per verificare la password

I passaggi sono:

  1. Derivare una chiave dalla password con la KDF e i suoi parametri. PBKDF2 è specificato nella RFC 8018, scrypt nella RFC 7914.
  2. Calcolare il MAC come hash Keccak-256 dei byte da 16 a 31 della chiave derivata seguiti dal testo cifrato, e confrontarlo con il campo mac.
  3. Se il MAC coincide, usare i primi 16 byte della chiave derivata come chiave AES.
  4. Decifrare il testo cifrato con AES-128-CTR, usando il valore iv del file.

Il controllo MAC dice se la password era corretta prima di tentare la decifratura. Una password errata produce una chiave derivata diversa e quindi un MAC diverso.

Come si decifra un file keystore in PHP?

Si usa hash_pbkdf2() per PBKDF2, openssl_decrypt() per AES e una libreria Keccak-256 per il MAC. La funzione integrata hash('sha3-256') di PHP è la SHA-3 del NIST, che dà un risultato diverso da Keccak-256. Installate la libreria in puro PHP con Composer:

Terminal window
composer require kornrunner/keccak

I keystore scrypt richiedono anche l’estensione php-scrypt, installabile con pecl install scrypt. I keystore PBKDF2 non ne hanno bisogno. L’estensione openssl è attiva nella maggior parte delle build di 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;

La chiave derivata è conservata come stringa esadecimale, quindi ogni byte occupa due caratteri. Per questo la chiave è substr($derivedKey, 0, 32) e la parte del MAC inizia al carattere 32.

Il codice funziona con un vettore di test noto?

Sì per PBKDF2. La specifica contiene un vettore di test PBKDF2 con la password testpassword. Abbiamo eseguito il ramo PBKDF2 di questo codice su quel vettore, e ha stampato il segreto 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d indicato nella specifica. La stessa esecuzione con una password errata si ferma al controllo MAC. Non abbiamo testato in PHP il ramo scrypt, quindi provatelo su un keystore di cui conoscete già la chiave prima di farvi affidamento.

Perché il controllo MAC fallisce?

Un MAC non corrispondente ha quattro cause frequenti:

  • La password è errata. È la causa più probabile.
  • La funzione di hash è SHA3-256 del NIST invece di Keccak-256. Entrambe in alcune librerie si chiamano SHA-3, ma differiscono nel padding e producono output diversi.
  • La chiave derivata è stata tagliata nel punto sbagliato. Il MAC usa i byte da 16 a 31, mentre la chiave del cifrario usa i byte da 0 a 15.
  • Il salt è stato usato come testo invece di essere decodificato da esadecimale.

Un keystore scrypt con n pari a 262144 e r pari a 8 richiede circa 256 MiB di memoria per la derivazione, poiché la RFC 7914 indica un uso di memoria di circa 128 × N × r byte. Su un server piccolo può fallire oppure richiedere diversi secondi.

È sicuro decifrare un keystore su una macchina connessa?

Evitatelo. Una volta stampata la chiave privata, qualsiasi malware, file di log o cronologia della shell su quella macchina può catturarla. Decifrate su una macchina offline, cancellate la cronologia del terminale dopo l’uso e non incollate mai una chiave o un keystore su un sito che non controllate.

Pubblichiamo anche un Keystore Decryptor gratuito su GitHub. Il suo README dice che funziona interamente nel browser, basandosi sulla libreria keythereum, e che non invia mai dati a un server. Per usarlo offline, clonate il repository, disconnettetevi dalla rete e aprite index.html. Leggete il codice sorgente prima di usare qualsiasi strumento che gestisce chiavi. Per indicazioni generali sulla gestione delle chiavi, vedete i nostri consigli di sicurezza.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.