@acyclic/keythereum 中文文档教程

Question

@acyclic/keythereum

Note: This project is a fork of the keythereum project.

Keythereum 是一个用于生成、导入和导出以太坊密钥的 JavaScript 工具。 这提供了一种在本地和网络钱包中使用相同帐户的简单方法。 可用于可验证冷钱包。

Keythereum 使用与 geth. 您可以将生成的密钥导出到文件，将其复制到数据目录的密钥库，然后立即开始在本地以太坊客户端中使用它。

注意：从 0.5.0 版本开始，keythereum 的 encrypt 和 decrypt 函数都返回 Buffers 而不是字符串。 对于直接使用这些函数的任何人来说，这都是一个重大变化！

Installation

npm install @acyclic/keythereum

Usage

要在 Node.js 中使用 keythereum，只需 require 它：

var keythereum = require("@acyclic/keythereum");

一个缩小的、浏览器化的文件 dist/keythereum.min.js 包含在浏览器中使用。 包含此文件只是将 keythereum 对象附加到 window：

<script src="dist/keythereum.min.js" type="text/javascript"></script>

Key creation

生成一个新的随机私钥（256 位），以及用于密钥派生的盐（256 位）函数，以及用于 AES-128-CTR 加密密钥的初始化向量（128 位）。 create 如果传递给回调函数则为异步，否则为同步。

// optional private key and initialization vector sizes in bytes
// (if params is not passed to create, keythereum.constants is used by default)
var params = { keyBytes: 32, ivBytes: 16 };

// synchronous
var dk = keythereum.create(params);
// dk:
{
    privateKey: <Buffer ...>,
    iv: <Buffer ...>,
    salt: <Buffer ...>
}

// asynchronous
keythereum.create(params, function (dk) {
    // do stuff!
});

Key export

您将需要指定密码和（可选）密钥派生函数。 如果未指定，PBKDF2-SHA256 将用于派生 AES 密钥。

var password = "wheethereum";
var kdf = "pbkdf2"; // or "scrypt" to use the scrypt kdf

dump 函数用于将密钥信息导出到密钥库 "secret-storage " 格式。 如果回调函数作为第六个参数提供给 dump，它将异步运行：

// Note: if options is unspecified, the values in keythereum.constants are used.
var options = {
  kdf: "pbkdf2",
  cipher: "aes-128-ctr",
  kdfparams: {
    c: 262144,
    dklen: 32,
    prf: "hmac-sha256"
  }
};

// synchronous
var keyObject = keythereum.dump(password, dk.privateKey, dk.salt, dk.iv, options);
// keyObject:
{
  address: "008aeeda4d805471df9b2a5b0f38a0c3bcba786b",
  Crypto: {
    cipher: "aes-128-ctr",
    ciphertext: "5318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46",
    cipherparams: {
      iv: "6087dab2f9fdbbfaddc31a909735c1e6"
    },
    mac: "517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2",
    kdf: "pbkdf2",
    kdfparams: {
      c: 262144,
      dklen: 32,
      prf: "hmac-sha256",
      salt: "ae3cd4e7013836a3df6bd7241b12db061dbe2c6785853cce422d148a624ce0bd"
    }
  },
  id: "e13b209c-3b2f-4327-bab0-3bef2e51630d",
  version: 3
}

// asynchronous
keythereum.dump(password, dk.privateKey, dk.salt, dk.iv, options, function (keyObject) {
  // do stuff!
});

dump 创建一个对象而不是 JSON 字符串。 在 Node 中，exportToFile 方法提供了一种将此格式化的键对象导出到文件的简单方法。 它在 keystore 子目录中创建一个 JSON 文件，并使用 geth 的当前文件命名约定（ISO 时间戳与密钥的派生以太坊地址连接）。

keythereum.exportToFile(keyObject);

成功导出密钥后，您将看到如下消息：

Saved to file:
keystore/UTC--2015-08-11T06:13:53.359Z--008aeeda4d805471df9b2a5b0f38a0c3bcba786b

To use with geth, copy this file to your Ethereum keystore folder
(usually ~/.ethereum/keystore).

Key import

Importing a key from geth's keystore can only done on Node. JSON文件被解析为一个对象，其结构与上面的keyObject相同。

// Specify a data directory (optional; defaults to ~/.ethereum)
var datadir = "/home/jack/.ethereum-test";

// Synchronous
var keyObject = keythereum.importFromFile(address, datadir);

// Asynchronous
keythereum.importFromFile(address, datadir, function (keyObject) {
  // do stuff
});

这已通过版本 3 和版本 1 测试，但未使用版本 2 密钥进行测试。 （如果你有一个版本 2 的密钥库文件，请发给我，这样我可以测试它！）

要从密钥对象恢复明文私钥，请使用 keythereum.recover。 私钥作为缓冲区返回。

// synchronous
var privateKey = keythereum.recover(password, keyObject);
// privateKey:
<Buffer ...>

// Asynchronous
keythereum.recover(password, keyObject, function (privateKey) {
  // do stuff
});

Hashing rounds

默认情况下，keythereum 在其密钥派生函数中使用 65536 轮哈希，而 geth 默认使用 262144 轮。 （但是，Keythereum 的 JSON 输出文件仍然与 geth 兼容，因为它们告诉 geth 要使用多少轮。）这些值是用户可编辑的：keythereum.constants.pbkdf2.c 是轮数对于 PBKDF2，keythereum.constants.scrypt.n 是 scrypt 的轮数。

Tests

单元测试在 test 目录中，可以用 mocha 运行：

npm test

test/geth.js 是一个集成测试，它运行（与 test/ keys.js) 使用：

npm run geth

geth.js 生成 1000 个随机私钥，使用随机生成的密码加密每个密钥，将加密的密钥信息转储到 JSON 文件，然后生成一个 geth实例并尝试使用其密码和 JSON 文件解锁每个帐户。 密码介于 1 到 100 个随机字节之间。 每个密码短语都经过十六进制和 base-64 编码以及 PBKDF2-SHA256 和 scrypt 密钥派生函数的测试。

默认情况下，传递给 geth 的标志是：

geth --etherbase <account> --unlock <account> --nodiscover --networkid "10101" --port 30304 --rpcport 8547 --datadir test/fixtures --password test/fixtures/.password

test/fixtures/.password 是一个包含密码的文件。 .password 文件，以及 geth.js 生成的 JSON 密钥文件，在测试后会自动删除。

（注意：geth.js 进行 4000 次测试，每次测试最多可能需要 5 秒，因此运行此文件最多可能需要 5.56 小时。）