Déchiffrer un keystore en PHP : Ethereum, BNB, Polygon
Comment déchiffrer en PHP un fichier keystore Ethereum (Web3 Secret Storage v3) : exemple PBKDF2 testé, contrôle du MAC et erreurs courantes.
Relu par Maurice Sobiera
Un fichier keystore est un fichier JSON qui stocke une clé privée de type Ethereum, chiffrée par un mot de passe, selon la Web3 Secret Storage Definition, version 3. Ethereum, BNB Smart Chain et Polygon utilisent tous ce format. Pour le déchiffrer, on dérive une clé à partir du mot de passe, on vérifie le MAC, puis on déchiffre le texte chiffré avec AES-128-CTR.
Qu’est-ce qu’un fichier keystore ?
Un fichier keystore permet à une application de conserver une clé privée sur disque sans la stocker en clair. Le fichier contient la clé chiffrée, les paramètres nécessaires pour dériver la clé de chiffrement à partir d’un mot de passe, et une somme de contrôle appelée MAC. Quiconque possède le fichier et le mot de passe peut récupérer la clé privée : traitez donc les deux comme des secrets.
Le format est décrit dans la Web3 Secret Storage Definition sur ethereum.org. Le même fichier fonctionne sur tous les réseaux EVM, car la clé et l’adresse y sont dérivées de la même manière.
Comment fonctionne le déchiffrement d’un keystore ?
Le déchiffrement suit quatre étapes définies par la spécification. L’objet crypto du fichier contient tout ce dont vous avez besoin :
| Champ | Signification |
|---|---|
kdf | Fonction de dérivation de clé, pbkdf2 ou scrypt |
kdfparams | Paramètres de la KDF : salt, dklen, et c (PBKDF2) ou n, r, p (scrypt) |
cipher | Algorithme de chiffrement, aes-128-ctr pour les fichiers conformes |
cipherparams.iv | Vecteur d’initialisation du chiffrement |
ciphertext | La clé privée chiffrée |
mac | Somme de contrôle utilisée pour vérifier le mot de passe |
Les étapes sont les suivantes :
- Dérivez une clé à partir du mot de passe avec la KDF et ses paramètres. PBKDF2 est spécifié dans la RFC 8018, scrypt dans la RFC 7914.
- Calculez le MAC comme le hachage Keccak-256 des octets 16 à 31 de la clé dérivée, suivis du texte chiffré, puis comparez-le au champ
mac. - Si le MAC correspond, prenez les 16 premiers octets de la clé dérivée comme clé AES.
- Déchiffrez le texte chiffré avec AES-128-CTR, en utilisant le
ivdu fichier.
La vérification du MAC indique si le mot de passe est bon avant même de tenter le déchiffrement. Un mauvais mot de passe donne une autre clé dérivée, donc un autre MAC.
Comment déchiffrer un fichier keystore en PHP ?
Utilisez hash_pbkdf2() pour PBKDF2, openssl_decrypt() pour AES, et une bibliothèque Keccak-256 pour le MAC. La fonction intégrée hash('sha3-256') de PHP est la fonction SHA-3 du NIST, qui donne un résultat différent de Keccak-256. Installez la bibliothèque PHP pure avec Composer :
composer require kornrunner/keccakLes keystores scrypt nécessitent aussi l’extension php-scrypt, installable avec pecl install scrypt. Les keystores PBKDF2 n’en ont pas besoin. L’extension openssl est activée dans la plupart des builds 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 clé dérivée est conservée sous forme de chaîne hexadécimale, si bien que chaque octet occupe deux caractères. C’est pourquoi la clé est substr($derivedKey, 0, 32) et que la partie MAC commence au caractère 32.
Le code fonctionne-t-il sur un vecteur de test connu ?
Oui pour PBKDF2. La spécification contient un vecteur de test PBKDF2 avec le mot de passe testpassword. Nous avons exécuté la branche PBKDF2 de ce code sur ce vecteur, et elle a affiché le secret 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d donné dans la spécification. La même exécution avec un mauvais mot de passe s’arrête à la vérification du MAC. Nous n’avons pas testé la branche scrypt en PHP : exécutez-la donc sur un keystore dont vous connaissez déjà la clé avant de vous y fier.
Pourquoi la vérification du MAC échoue-t-elle ?
Un échec de vérification du MAC a quatre causes fréquentes :
- Le mot de passe est faux. C’est la cause la plus probable.
- La fonction de hachage est SHA3-256 du NIST au lieu de Keccak-256. Les deux sont appelées SHA-3 dans certaines bibliothèques, mais elles diffèrent par le padding et produisent des résultats différents.
- La clé dérivée a été coupée au mauvais endroit. Le MAC utilise les octets 16 à 31, et la clé de chiffrement utilise les octets 0 à 15.
- Le sel a été utilisé comme texte au lieu d’être décodé depuis l’hexadécimal.
Un keystore scrypt avec n égal à 262144 et r égal à 8 nécessite environ 256 Mio de mémoire pour la dérivation, puisque la RFC 7914 donne une consommation mémoire d’environ 128 × N × r octets. Sur un petit serveur, cela peut échouer ou prendre plusieurs secondes.
Est-il sûr de déchiffrer un keystore sur une machine connectée ?
Évitez-le. Une fois la clé privée affichée, tout logiciel malveillant, tout fichier journal ou tout historique de shell de cette machine peut la capturer. Déchiffrez sur une machine hors ligne, effacez ensuite l’historique du terminal, et ne collez jamais une clé ni un keystore dans un site que vous ne contrôlez pas.
Nous publions aussi un Keystore Decryptor gratuit sur GitHub. Son README indique qu’il fonctionne entièrement dans votre navigateur, s’appuie sur la bibliothèque keythereum, et n’envoie jamais de données à un serveur. Pour l’utiliser hors ligne, clonez le dépôt, déconnectez-vous du réseau et ouvrez index.html. Lisez le code source avant d’utiliser tout outil qui manipule des clés. Pour des conseils généraux sur la gestion des clés, consultez nos conseils de sécurité.
Comment nous rédigeons ces articles
Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.