Pular para o conteúdo principal
Change page

Definição de armazenamento secreto Web3

Última atualização da página: 21 de outubro de 2025

MCreimerM (opens in a new tab)
rafarochar (opens in a new tab)
pete-vielhaberp (opens in a new tab)
+6

Para fazer seu aplicativo funcionar no Ethereum, você pode usar o objeto web3 fornecido pela biblioteca web3.js. Internamente, ele se comunica com um nó local por meio de chamadas RPC. web3 (opens in a new tab) funciona com qualquer nó Ethereum que expõe uma camada RPC.

web3 contém o objeto 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/** resultado
10 *               [ 'web3', 3 ]   arquivo de chave web3 (v3)
11 *  [ 'ethersale', undefined ]   arquivo de chave Ethersale
12 *                        null     arquivo de chave inválido
13 */
Exibir tudo

Este documento descreve a versão 3 da Definição de Armazenamento Secreto da Web3.

Definição

A codificação e decodificação atuais do arquivo permanece em grande medida inalteradas da versão 1, exceto que o algoritmo cripto já não é fixo no AES-128-CBC (AES-128-CTR agora é o requisito mínimo). A maioria dos significados/algoritmos são semelhantes à versão 1, exceto o mac, que é dado como o SHA3 (keccak-256) das concatenações dos segundos 16 bytes mais à esquerda da chave derivada, juntamente com o ciphertext completo.

Arquivos de chave secreta são armazenados diretamente em ~/.web3/keystore (para sistemas do tipo Unix) e ~/AppData/Web3/keystore (para Windows). Eles podem receber qualquer nome, mas uma boa convenção é <uuid>.json, onde <uuid> é o UUID de 128 bits atribuído à chave secreta (um proxy de preservação de privacidade para o endereço da chave secreta).

Todos esses arquivos possuem uma senha associada. Para derivar a chave secreta de um determinado arquivo .json, primeiro derive a chave de criptografia do arquivo; isso é feito pegando a senha do arquivo e passando-a por uma função de derivação de chave, conforme descrito pela chave kdf. Os parâmetros estáticos e dinâmicos dependentes do KDF para a função KDF são descritos na chave kdfparams.

PBKDF2 deve ser apoiado por todas as implementações minimamente compatíveis, denotadas assim:

  • kdf: pbkdf2

Para PBKDF2, os kdfparams incluem:

  • prf: Deve ser hmac-sha256 (pode ser estendido no futuro);
  • c: número de iterações;
  • salt: salt (sequência de bits aleatórios) passado para o PBKDF;
  • dklen: comprimento da chave derivada. Deve ser >= 32.

Uma vez que a chave do arquivo tenha sido derivada, ela deveria ser verificada através da derivação do MAC. O MAC deve ser calculado como o hash SHA3 (keccak-256) do array de bytes formado pelas concatenações dos segundos 16 bytes mais à esquerda da chave derivada com o conteúdo da chave ciphertext, ou seja:

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

(onde ++ é o operador de concatenação)

Este valor deve ser comparado com o conteúdo da chave mac; se forem diferentes, uma senha alternativa deve ser solicitada (ou a operação cancelada).

Após a verificação da chave do arquivo, o texto cifrado (a chave ciphertext no arquivo) pode ser descriptografado usando o algoritmo de criptografia simétrica, especificado pela chave cipher e parametrizado através da chave cipherparams. Se o tamanho da chave derivada e o tamanho da chave do algoritmo forem incompatíveis, os zeros à esquerda, os bytes à direita da chave derivada deverão ser usados como a chave para o algoritmo.

Todas as implementações minimamente compatíveis devem suportar o algoritmo AES-128-CTR, indicado através de:

  • cipher: aes-128-ctr

Esta cifra toma os seguintes parâmetros, dados como chaves para a chave dos parâmetros de decifração:

  • iv: vetor de inicialização de 128 bits para a cifra.

A chave para a cifra são os 16 bytes mais à esquerda da chave derivada, ou seja, DK[0..15]

A criação/criptografia de uma chave secreta deve ser essencialmente o inverso dessas instruções. Certifique-se de que o uuid, o salt e o iv sejam realmente aleatórios.

Além do campo version, que deve atuar como um identificador "rígido" da versão, as implementações também podem usar o minorversion para rastrear alterações menores, que não quebram o formato.

Vetores de Teste

Detalhes:

  • Address: 008aeeda4d805471df9b2a5b0f38a0c3bcba786b
  • ICAP: XE542A5PZHH8PYIZUBEJEO0MFWRAPPIL67
  • UUID: 3198bc9c-6672-5ab3-d9954942343ae5b6
  • Password: testpassword
  • Secret: 7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d

PBKDF2-SHA-256

Vetor de teste usando AES-128-CTR e PBKDF2-SHA-256:

Conteúdo do arquivo ~/.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}
Exibir tudo

Intermediários:

Chave derivada: f06d69cdc7da0faffb1008270bca38f5e31891a3a773950e6d0fea48a7188551 Corpo do MAC: e31891a3a773950e6d0fea48a71885515318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46 MAC: 517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2 Chave de cifra: f06d69cdc7da0faffb1008270bca38f5

Scrypt

Vetor de teste usando AES-128-CTR e 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}
Exibir tudo

Intermediários:

Chave derivada: 7446f59ecc301d2d79bc3302650d8a5cedc185ccbb4bf3ca1ebd2c163eaa6c2d Corpo do MAC: edc185ccbb4bf3ca1ebd2c163eaa6c2ddd8a1132cf57db67c038c6763afe2cbe6ea1949a86abc5843f8ca656ebbb1ea2 MAC: 337aeb86505d2d0bb620effe57f18381377d67d76dac1090626aa5cd20886a7c Chave de cifra: 7446f59ecc301d2d79bc3302650d8a5c

Alterações da Versão 1

Esta versão corrige várias inconsistências com a versão 1 publicada aqui (opens in a new tab). Em resumo, estas são:

  • A capitalização é injustificada e inconsistente (scrypt minúsculas, Kdf caso misto, MAC maiúsculas).
  • Endereço desnecessário e compromete a privacidade.
  • Salt é intrinsecamente um parâmetro da função de derivação de chave e merece ser associado a ela, não à criptografia em geral.
  • SaltLen desnecessário (basta derivá-lo do Salt).
  • A função chave de derivação é dada, no entanto, o algoritmo de criptografia é difícil de especificar.
  • Version é intrinsecamente numérico, mas é uma string (o versionamento estruturado seria possível com uma string, mas pode ser considerado fora do escopo para um formato de arquivo de configuração que muda raramente).
  • KDF e cipher são conceitos conceitualmente semelhantes, mas organizados de forma diferente.
  • MAC é calculado através de um trecho de dados agnóstico a espaços em branco(!)

Foram feitas alterações no formato para dar o seguinte arquivo, funcionalmente equivalente ao exemplo dado na página anteriormente vinculada:

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}
Exibir tudo

Alterações da Versão 2

A versão 2 foi uma implementação inicial de C++ com um número de bugs. Todos os elementos essenciais permanecem inalterados.

Este artigo foi útil?