Définition du stockage secret Web3

Pour que votre application fonctionne sur Ethereum, vous pouvez utiliser l'objet web3 fourni par la bibliothèque web3.js. Il communique à un nœud local par le biais des appels RPC. web3 (opens in a new tab) fonctionne avec n'importe quel nœud Ethereum qui expose une couche RPC.

web3 contient l'objet eth - web3.eth.

1var fs = require("fs")
2var recognizer = require("ethereum-keyfile-recognizer")
3
4fs.readFile("keyfile.json", (err, data) => {
5  var json = JSON.parse(data)
6  var result = recognizer(json)
7})
8
9/** résultat
10 *               [ 'web3', 3 ]   fichier de clés web3 (v3)
11 *  [ 'ethersale', undefined ]   fichier de clés Ethersale
12 *                        null     fichier de clés invalide
13 */
Afficher tout

Ce document présente la version 3 de la Définition du Stockage Secret Web3.

Définition

L'encodage et le décodage du fichier restent en grande partie inchangés depuis la version 1, sauf que l'algorithme de cryptage n'est plus fixé à AES-128-CBC (AES-128-CTR est maintenant le minimum requis). La plupart des significations/algorithmes sont similaires à la version 1, à l'exception du mac, qui correspond au SHA3 (keccak-256) de la concaténation du deuxième bloc de 16 octets de la clé dérivée avec le ciphertext complet.

Les fichiers de clés secrètes sont stockés directement dans ~/.web3/keystore (pour les systèmes de type Unix) et ~/AppData/Web3/keystore (pour Windows). Leur nom est libre, mais une bonne convention est d'utiliser <uuid>.json, où <uuid> est l'UUID de 128 bits attribué à la clé secrète (un proxy qui préserve la confidentialité pour l'adresse de la clé secrète).

Tous ces fichiers ont un mot de passe associé. Pour dériver la clé secrète d'un fichier .json donné, dérivez d'abord la clé de chiffrement du fichier. Pour ce faire, prenez le mot de passe du fichier et passez-le dans une fonction de dérivation de clé, comme le décrit la clé kdf. Les paramètres statiques et dynamiques, dépendants de KDF, de la fonction KDF sont décrits dans la clé kdfparams.

PBKDF2 doit cependant être pris en charge par toutes les implémentations minimalement conformes, désignées par :

kdf : pbkdf2

Pour PBKDF2, les kdfparams incluent :

prf : Doit être hmac-sha256 (pourra être étendu à l'avenir) ;
c : nombre d'itérations ;
salt : sel passé à PBKDF ;
dklen : longueur de la clé dérivée. Doit être >= 32.

Une fois que la clé du fichier a été dérivée, elle doit être vérifiée par la dérivation du MAC. Le MAC doit être calculé comme le hachage SHA3 (keccak-256) du tableau d'octets formé par la concaténation du deuxième bloc de 16 octets de la clé dérivée avec le contenu de la clé ciphertext, c'est-à-dire :

1KECCAK(DK[16..31] ++ <ciphertext>)

(où ++ est l'opérateur de concaténation)

Cette valeur doit être comparée au contenu de la clé mac ; si elles sont différentes, un autre mot de passe doit être demandé (ou l'opération annulée).

Une fois la clé du fichier vérifiée, le texte chiffré (la clé ciphertext dans le fichier) peut être déchiffré à l'aide de l'algorithme de chiffrement symétrique spécifié par la clé cipher et paramétré par la clé cipherparams. Si la taille de la clé dérivée et la taille de la clé de l'algorithme ne correspondent pas, les octets zéro les plus à droite de la clé dérivée doivent être utilisés comme clé de l'algorithme.

Toutes les implémentations minimalement conformes doivent supporter l'algorithme AES-128-CTR, désigné par :

cipher : aes-128-ctr

Ce procédé de chiffrement prend les paramètres suivants, donnés comme clés de la clé des paramètres de chiffrement :

iv : vecteur d'initialisation de 128 bits pour le chiffrement.

La clé pour le chiffrement correspond aux 16 premiers octets de la clé dérivée, c'est-à-dire DK[0..15].

La création/Le cryptage d'une clé secrète doit être essentiellement l'inverse de ces instructions. Assurez-vous que l'uuid, le salt et l'iv sont bien aléatoires.

En plus du champ version, qui doit servir d'identifiant « en dur » de la version, les implémentations peuvent également utiliser minorversion pour suivre les modifications plus petites et sans rupture de compatibilité du format.

Vecteurs de test

Détails :

Adresse : 008aeeda4d805471df9b2a5b0f38a0c3bcba786b
ICAP : XE542A5PZHH8PYIZUBEJEO0MFWRAPPIL67
UUID : 3198bc9c-6672-5ab3-d9954942343ae5b6
Mot de passe : testpassword
Secret : 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d

PBKDF2-SHA-256

Vecteur de test utilisant AES-128-CTR et PBKDF2-SHA-256 :

Contenu du fichier ~/.web3/keystore/3198bc9c-6672-5ab3-d9954942343ae5b6.json :

1{
2  "crypto": {
3    "cipher": "aes-128-ctr",
4    "cipherparams": {
5      "iv": "6087dab2f9fdbbfaddc31a909735c1e6"
6    },
7    "ciphertext": "5318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46",
8    "kdf": "pbkdf2",
9    "kdfparams": {
10      "c": 262144,
11      "dklen": 32,
12      "prf": "hmac-sha256",
13      "salt": "ae3cd4e7013836a3df6bd7241b12db061dbe2c6785853cce422d148a624ce0bd"
14    },
15    "mac": "517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2"
16  },
17  "id": "3198bc9c-6672-5ab3-d995-4942343ae5b6",
18  "version": 3
19}
Afficher tout

Intermédiaires :

Clé dérivée : f06d69cdc7da0faffb1008270bca38f5e31891a3a773950e6d0fea48a7188551 Corps MAC : e31891a3a773950e6d0fea48a71885515318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46 MAC : 517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2 Clé de chiffrement : f06d69cdc7da0faffb1008270bca38f5

Scrypt

Test de vecteur en utilisant AES-128-CTR et Scrypt :

1{
2  "crypto": {
3    "cipher": "aes-128-ctr",
4    "cipherparams": {
5      "iv": "740770fce12ce862af21264dab25f1da"
6    },
7    "ciphertext": "dd8a1132cf57db67c038c6763afe2cbe6ea1949a86abc5843f8ca656ebbb1ea2",
8    "kdf": "scrypt",
9    "kdfparams": {
10      "dklen": 32,
11      "n": 262144,
12      "p": 1,
13      "r": 8,
14      "salt": "25710c2ccd7c610b24d068af83b959b7a0e5f40641f0c82daeb1345766191034"
15    },
16    "mac": "337aeb86505d2d0bb620effe57f18381377d67d76dac1090626aa5cd20886a7c"
17  },
18  "id": "3198bc9c-6672-5ab3-d995-4942343ae5b6",
19  "version": 3
20}
Afficher tout

Intermédiaires :

Clé dérivée : 7446f59ecc301d2d79bc3302650d8a5cedc185ccbb4bf3ca1ebd2c163eaa6c2d Corps MAC : edc185ccbb4bf3ca1ebd2c163eaa6c2ddd8a1132cf57db67c038c6763afe2cbe6ea1949a86abc5843f8ca656ebbb1ea2 MAC : 337aeb86505d2d0bb620effe57f18381377d67d76dac1090626aa5cd20886a7c Clé de chiffrement : 7446f59ecc301d2d79bc3302650d8a5c

Modifications par rapport à la version 1

Cette version corrige plusieurs incohérences avec la version 1 publiée ici (opens in a new tab). En bref, il s'agit de :

La capitalisation est injustifiée et incohérente (Scrypt minuscule, Kdf mixte, Mac majuscule).
Adresse inutile et compromettant la vie privée.
Salt est intrinsèquement un paramètre de la fonction de dérivation de clé et mérite d'y être associé, et non à la crypto en général.
SaltLen inutile (il suffit de le dériver de Salt).
La fonction de dérivation de clé est donnée, mais l'algorithme de crypto n'est pas spécifié.
Version est intrinsèquement numérique, mais c'est une chaîne de caractères (la gestion de versions structurée serait possible avec une chaîne, mais peut être considérée comme hors de portée pour un format de fichier de configuration qui change rarement).
KDF et cipher sont théoriquement des concepts frères, mais ils sont organisés différemment.
Le MAC est calculé à l'aide d'une donnée insensible aux espaces ( !).

Des modifications ont été apportées au format pour donner le fichier suivant, équivalent sur le plan fonctionnel à l'exemple donné sur la page précédemment citée :

1{
2  "crypto": {
3    "cipher": "aes-128-cbc",
4    "ciphertext": "07533e172414bfa50e99dba4a0ce603f654ebfa1ff46277c3e0c577fdc87f6bb4e4fe16c5a94ce6ce14cfa069821ef9b",
5    "cipherparams": {
6      "iv": "16d67ba0ce5a339ff2f07951253e6ba8"
7    },
8    "kdf": "scrypt",
9    "kdfparams": {
10      "dklen": 32,
11      "n": 262144,
12      "p": 1,
13      "r": 8,
14      "salt": "06870e5e6a24e183a5c807bd1c43afd86d573f7db303ff4853d135cd0fd3fe91"
15    },
16    "mac": "8ccded24da2e99a11d48cda146f9cc8213eb423e2ea0d8427f41c3be414424dd",
17    "version": 1
18  },
19  "id": "0498f19a-59db-4d54-ac95-33901b4f1870",
20  "version": 2
21}
Afficher tout

Modifications par rapport à la version 2

La version 2 était une implémentation précoce C++ comportant un certain nombre d'anomalies. Tous les éléments essentiels restent inchangés.