Визначення секретного сховища Web3

Щоб ваш додаток працював на Ethereum, ви можете використовувати об’єкт web3, який надається бібліотекою web3.js. Під капотом він взаємодіє з локальним вузлом через RPC-виклики. web3 (opens in a new tab) працює з будь-яким вузлом Ethereum, що надає доступ до RPC-шару.

web3 містить об'єкт 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/** результат
10 *               [ 'web3', 3 ]   файл ключа web3 (v3)
11 *  [ 'ethersale', undefined ]   файл ключа Ethersale
12 *                        null     недійсний файл ключа
13 */
Показати все

Цей документ описує версію 3 визначення сховища секретів Web3.

Визначення

Фактичне кодування та декодування файлу залишається переважно без змін порівняно з версією 1, за винятком того, що криптоалгоритм більше не прив’язаний до AES-128-CBC (тепер мінімальною вимогою є AES-128-CTR). Більшість значень/алгоритмів схожі на версію 1, за винятком mac, який отримується як SHA3 (keccak-256) від об’єднання 16 байтів похідного ключа, других зліва, разом із повним ciphertext.

Файли секретних ключів зберігаються безпосередньо в ~/.web3/keystore (для Unix-подібних систем) і ~/AppData/Web3/keystore (для Windows). Їх можна називати як завгодно, але хорошою практикою є <uuid>.json, де <uuid> — це 128-бітний UUID, присвоєний секретному ключу (проксі для адреси секретного ключа, що зберігає конфіденційність).

Усі такі файли мають пов’язаний пароль. Щоб отримати секретний ключ із певного файлу .json, спочатку потрібно отримати ключ шифрування файлу; це робиться шляхом взяття пароля файлу й передачі його через функцію отримання ключа, як описано в ключі kdf. Статичні та динамічні параметри для функції KDF, що залежать від KDF, описані в ключі kdfparams.

PBKDF2 має підтримуватися всіма мінімально сумісними реалізаціями, що позначається так:

kdf: pbkdf2

Для PBKDF2 kdfparams містять:

prf: має бути hmac-sha256 (може бути розширено в майбутньому);
c: кількість ітерацій;
salt: сіль, що передається до PBKDF;
dklen: довжина похідного ключа. Має бути >= 32.

Після отримання ключа файлу його слід перевірити шляхом отримання MAC. MAC слід обчислювати як хеш SHA3 (keccak-256) масиву байтів, утвореного як об’єднання 16 байтів похідного ключа, других зліва, зі вмістом ключа ciphertext, тобто:

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

(де ++ — оператор об’єднання)

Це значення слід порівняти зі вмістом ключа mac; якщо вони відрізняються, слід запросити інший пароль (або скасувати операцію).

Після перевірки ключа файлу зашифрований текст (ключ ciphertext у файлі) можна розшифрувати за допомогою симетричного алгоритму шифрування, зазначеного в ключі cipher і параметризованого через ключ cipherparams. Якщо розмір похідного ключа та розмір ключа алгоритму не збігаються, праві байти похідного ключа, доповнені нулями, слід використовувати як ключ для алгоритму.

Усі мінімально сумісні реалізації повинні підтримувати алгоритм AES-128-CTR, що позначається так:

cipher: aes-128-ctr

Цей шифр приймає такі параметри, вказані як ключі в ключі cipherparams:

iv: 128-бітний вектор ініціалізації для шифру.

Ключем для шифру є 16 лівих байтів похідного ключа, тобто DK[0..15].

Створення/шифрування секретного ключа, по суті, має бути зворотним до цих інструкцій. Переконайтеся, що uuid, salt та iv є дійсно випадковими.

На додаток до поля version, яке має слугувати "жорстким" ідентифікатором версії, реалізації можуть також використовувати minorversion для відстеження менших, некритичних змін у форматі.

Тестові вектори

Деталі:

Адреса: 008aeeda4d805471df9b2a5b0f38a0c3bcba786b
ICAP: XE542A5PZHH8PYIZUBEJEO0MFWRAPPIL67
UUID: 3198bc9c-6672-5ab3-d9954942343ae5b6
Пароль: testpassword
Секрет: 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d

PBKDF2-SHA-256

Тестовий вектор із використанням AES-128-CTR та PBKDF2-SHA-256:

Вміст файлу ~/.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}
Показати все

Проміжні значення:

Похідний ключ: f06d69cdc7da0faffb1008270bca38f5e31891a3a773950e6d0fea48a7188551 Тіло MAC: e31891a3a773950e6d0fea48a71885515318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46 MAC: 517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2 Ключ шифрування: f06d69cdc7da0faffb1008270bca38f5

Scrypt

Тестовий вектор із використанням AES-128-CTR і 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}
Показати все

Проміжні значення:

Похідний ключ: 7446f59ecc301d2d79bc3302650d8a5cedc185ccbb4bf3ca1ebd2c163eaa6c2d Тіло MAC: edc185ccbb4bf3ca1ebd2c163eaa6c2ddd8a1132cf57db67c038c6763afe2cbe6ea1949a86abc5843f8ca656ebbb1ea2 MAC: 337aeb86505d2d0bb620effe57f18381377d67d76dac1090626aa5cd20886a7c Ключ шифрування: 7446f59ecc301d2d79bc3302650d8a5c

Зміни порівняно з версією 1

Ця версія виправляє кілька невідповідностей з версією 1, опублікованою тут (opens in a new tab). Коротко кажучи, це:

Написання великими літерами є невиправданим і непослідовним (scrypt малими літерами, Kdf у змішаному регістрі, MAC великими літерами).
Адреса непотрібна й порушує конфіденційність.
Salt за своєю суттю є параметром функції виведення ключа і має бути пов’язана з нею, а не з криптографією загалом.
SaltLen непотрібний (просто виведіть його з Salt).
Функція виведення ключа вказана, але криптоалгоритм жорстко визначений.
Version за своєю суттю є числом, але представлене рядком (структуроване керування версіями було б можливим за допомогою рядка, але це можна вважати таким, що виходить за межі формату конфігураційного файлу, який рідко змінюється).
KDF і cipher — це концептуально споріднені поняття, але організовані по-різному.
MAC обчислюється на основі даних, нечутливих до пробілів(!)

Було внесено зміни у формат, щоб отримати такий файл, функціонально еквівалентний прикладу, наведеному на сторінці за попереднім посиланням:

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}
Показати все

Зміни порівняно з версією 2

Версія 2 була ранньою реалізацією на C++ з низкою помилок. Усі основні елементи залишилися без змін.