parity-ethereum ethstore 密钥管理工具完全指南:命令用法、保险库机制与源码原理

原创2026-10-14 14:52:081,425 阅读
文章标签:区块链

parity-ethereum ethstore 密钥管理工具完全指南:命令用法、保险库机制与源码原理

导读

ethstore 是 parity-ethereum 项目中的以太坊密钥管理工具(key management),负责账户密钥的安全存储、导入导出、签名与密码管理。本文以官方 README 为骨架,逐一解析 ethstore-cli 的 14 个命令与全部命令行选项,并结合 CLI 入口源码、存储实现、加密实现 等源码,讲清每个命令的底层调用链与设计意图。读完本文,你将能够使用 ethstore 完成账户创建、密码修改、账户迁移、presale 钱包导入、消息签名、公钥导出,以及 vault 保险库的完整生命周期管理。

一、ethstore 是什么

ethstore 是 Parity Ethereum 的官方密钥管理组件,位于 accounts/ethstore 目录,对应 crate 名 ethstore(版本 0.2.1,见 Cargo.toml)。它在整个工具链中的职责是:

  • 安全落盘:把 32 字节的以太坊私钥(secret)用密码加密后写入密钥库文件(keystore),文件格式遵循以太坊标准 V3 密钥文件(version: 3,见 account/version.rs 中 Version::V3 枚举);
  • 统一访问入口:对外提供 EthStore / EthMultiStore 两个存储实现,以及 SimpleSecretStore / SecretStore 两组 trait API(定义见 secret_store.rs);
  • 跨客户端迁移:支持从 geth 密钥目录批量导入账户;
  • vault 保险库:支持以“保险库”为单位对账户二次分组加密,vault 自身也有独立密码。

在 Parity Ethereum 工具链中,它与 accounts/ethkey(密钥生成器)、evmbin(EVM 实现)等组件协作:ethkey 负责生成随机密钥对,ethstore 负责把密钥安全地保存下来,二者常常组合使用(见下文 insert 命令示例)。

二、构建与运行

ethstore 是 Rust crate,可通过 Cargo 构建。在仓库根目录执行:

cargo build -p ethstore

构建产物位于 target/debug/ 下(发行版使用 cargo build -p ethstore --release)。运行 ethstore -h 或 ethstore --help 会打印完整帮助信息并退出。需要说明的是,CLI 通过 docopt 解析参数(main.rs),因此所有命令语法都必须与帮助文档中的 Usage: 行完全一致。

三、完整命令一览

3.1 Usage 全文

Parity Ethereum key management tool.
  Copyright 2015-2020 Parity Technologies (UK) Ltd.

Usage:
    ethstore insert <secret> <password> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore change-pwd <address> <old-pwd> <new-pwd> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore list [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore import [--src DIR] [--dir DIR]
    ethstore import-wallet <path> <password> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore find-wallet-pass <path> <password>
    ethstore remove <address> <password> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore sign <address> <password> <message> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore public <address> <password> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore list-vaults [--dir DIR]
    ethstore create-vault <vault> <password> [--dir DIR]
    ethstore change-vault-pwd <vault> <old-pwd> <new-pwd> [--dir DIR]
    ethstore move-to-vault <address> <vault> <password> [--dir DIR] [--vault VAULT] [--vault-pwd VAULTPWD]
    ethstore move-from-vault <address> <vault> <password> [--dir DIR]
    ethstore [-h | --help]

(该 Usage 字符串同样以 USAGE 常量形式内嵌在 main.rs 中,是 docopt 生成参数解析器的唯一数据源。)

3.2 全局选项

选项 含义 说明
-h, --help 打印帮助并退出 —
--dir DIR 指定密钥库目录 可以是 parity、parity-(chain)、geth、geth-test 或任意路径,默认 parity
--vault VAULT 本次操作使用的保险库 使用该选项时必须同时给出 --vault-pwd,否则被忽略
--vault-pwd VAULTPWD 保险库密码文件路径 设置 --vault 时必填;未设置 --vault 时该选项被忽略
--src DIR 导入源目录 取值同 --dir,默认 geth,仅 import 命令使用

--dir 的取值在 main.rs 的 key_dir 函数中解析:

  • geth → geth 主网密钥目录(dir::geth(false));
  • geth-test → geth 测试网密钥目录(dir::geth(true));
  • 以 parity 开头 → 按 parity-(chain) 形式拆出链名(默认 ethereum),解析为对应链的 parity 密钥目录;
  • 其他任意字符串 → 直接视为文件系统路径。

3.3 关于密码的重要约定

文档中所有 <password>、<old-pwd>、<new-pwd>、<vault-pwd> 参数都是密码文件路径,而不是明文密码字符串。源码中的 load_password 函数会打开该文件、读取全部内容并去掉末尾换行符后作为密码使用(main.rs)。因此使用前需要先准备密码文件,例如:

echo -n "my password" > password.txt

四、账户常用命令实战

4.1 insert <secret> <password> — 保存账户

Encrypt secret with a password and save it in secret store.

参数:

  • <secret>:32 字节以太坊私钥(hex 字符串)
  • <password>:账户密码文件路径
  • [--dir DIR]:密钥库目录,默认 parity
  • [--vault VAULT] / [--vault-pwd VAULTPWD]:可选,写入指定保险库

示例:

ethstore insert 7d29fab185a33e2cd955812397354c472d2b84615b645aa135ff539f6b0d70d5 password.txt

输出(新账户地址):

a8fa5dd30a87bb9e3288d604eb74949c515ab66e

与 ethkey 组合,随机生成密钥并入库:

ethstore insert `ethkey generate random -s` "this is sparta"
24edfff680d536a5f6fe862d36df6f8f6f40f115

注意:上面第二条命令中密码直接以字符串形式写在命令里,是因为 shell 把它当作参数传入 load_password——但按照源码逻辑,任何非文件路径都会在打开文件时报错。因此规范用法仍是先写密码文件再传文件路径。

源码视角:insert 分支先解析 secret,然后调用 store.insert_account(vault_ref, secret, &password)(main.rs)。底层在 ethstore.rs 中:用 KeyPair::from_secret 从私钥推导地址,生成随机 UUID(Random::random()),构造 SafeAccount(版本 V3),随后写入磁盘。落盘时文件名遵循 UTC--<时间戳>Z--<uuid> 格式(disk.rs),若文件名冲突则追加 4 位随机后缀去重,并强制把文件权限限制为仅属主可读写(S_IWUSR | S_IRUSR,见 disk.rs)。

4.2 change-pwd <address> <old-pwd> <new-pwd> — 修改密码

Change account password.

参数:

  • <address>:20 字节账户地址
  • <old-pwd> / <new-pwd>:旧/新密码文件路径

示例:

ethstore change-pwd a8fa5dd30a87bb9e3288d604eb74949c515ab66e old_pwd.txt new_pwd.txt

输出:

true

源码视角:命令输出 true 或 false 取决于 store.change_password 是否成功(main.rs)。底层先用旧密码解出私钥,再以新密码重新加密生成新的 SafeAccount 并原子替换旧文件(ethstore.rs)。safe_account.rs 中的 change_password 保留 id、地址、文件名、name、meta 等所有字段,仅重做加密层。

4.3 list — 列出账户

List secret store accounts.

示例:

ethstore list

输出(编号 + 地址):

 0: 24edfff680d536a5f6fe862d36df6f8f6f40f115
 1: 6edddfc6349aff20bc6467ccf276c5b52487f7a8
 2: e6a3d25a7cb7cd21cb720df5b5e8afd154af1bbb

源码视角:list 会读取 store.accounts() 全部账户,再按 SecretVaultRef 过滤出与当前 --vault 匹配的条目并格式化输出(main.rs)。EthMultiStore::accounts() 会先调用 reload_if_changed() 按需重读磁盘目录(ethstore.rs)。

4.4 import — 批量导入账户

Import accounts from src.

参数:

  • [--src DIR]:导入源目录,默认 geth
  • [--dir DIR]:目标目录,默认 parity

示例:

ethstore import

输出(本次实际导入的账户列表):

 0: e6a3d25a7cb7cd21cb720df5b5e8afd154af1bbb
 1: 6edddfc6349aff20bc6467ccf276c5b52487f7a8

源码视角:import_accounts 遍历源目录全部密钥文件,读取每个 SafeAccount,与目标目录已有地址去重后仅插入“地址不存在”的账户(import.rs)。CLI 中 key_dir(&args.flag_src, password) 支持给源目录附加可选密码,用于导入不含地址字段、必须靠密码推导地址的密钥文件(main.rs;该能力源自 RootDiskDirectory::with_password,见 disk.rs)。

4.5 import-wallet <path> <password> — 导入 presale 钱包

Import account from presale wallet.

参数:

  • <path>:presale 钱包 JSON 文件路径
  • <password>:钱包密码文件路径

示例:

ethstore import-wallet ethwallet.json password.txt

输出(新账户地址):

e6a3d25a7cb7cd21cb720df5b5e8afd154af1bbb

源码视角:presale 钱包是 2015 年以太坊预售期钱包格式,encseed 字段用密码经 PBKDF2-HMAC-SHA256(2000 轮)派生密钥后以 AES-128-CBC 加密种子,解密后再对明文做 Keccak256 得到私钥(presale.rs)。import-wallet 分支调用 PresaleWallet::open + decrypt,得到密钥对后调用 insert_account 入库(main.rs)。ethstore 仓库自带的测试用 "123" 密码验证了解密成功、"124" 验证失败(presale.rs)。

4.6 find-wallet-pass <path> <password> — 爆破 presale 钱包密码

Try to open presale wallet given a list of passwords from a file. The list of passwords can be generated using e.g. Phildo/brutedist.

参数:

  • <path>:presale 钱包路径
  • <password>:候选密码列表文件路径(每行一个)

示例:

ethstore find-wallet-pass ethwallet.json passwords.txt

输出:

Found password: test

源码视角:该命令按 CPU 核数(num_cpus::get())开启多个线程并行尝试候选密码,每个线程每次取最多 32 个候选批量解密,命中即打印 Found password: <pass> 并停止;未命中则每尝试 100 个打印一个 .(crack.rs)。全部尝试完仍未命中时主程序打印 Password not found.(main.rs)。

4.7 remove <address> <password> — 删除账户

Remove account from secret store.

参数:

  • <address>:账户地址
  • <password>:账户密码文件路径

示例:

ethstore remove a8fa5dd30a87bb9e3288d604eb74949c515ab66e password.txt

输出:

true

源码视角:remove_account 先用密码校验匹配账户(get_matching,即密码不正确则返回 InvalidPassword 导致输出 false),再删除磁盘文件并更新内存缓存(ethstore.rs)。测试 tests/api.rs 验证了删除成功后账户数归零、重复删除会报错的行为。

4.8 sign <address> <password> <message> — 消息签名

Sign message with account's secret.

参数:

  • <address>:账户地址
  • <password>:账户密码文件路径
  • <message>:待签名消息,32 字节

示例:

ethstore sign 24edfff680d536a5f6fe862d36df6f8f6f40f115 password.txt 7d29fab185a33e2cd955812397354c472d2b84615b645aa135ff539f6b0d70d5

输出(65 字节签名 hex,r/s/v 三段):

c6649f9555232d90ff716d7e552a744c5af771574425a74860e12f763479eb1b708c1f3a7dc0a0a7f7a81e0a0ca88c6deacf469222bb3d9c5bf0847f98bae54901

源码视角:sign 分支调用 store.sign(&account_ref, &password, &message)(main.rs)。底层流程是:用密码解密出私钥 → sign(&secret, message) 产出签名(safe_account.rs)。tests/api.rs 用正确/错误密码验证了签名成功与失败路径,并用 verify_address 校验签名归属地址。

4.9 public <address> <password> — 导出公钥

Displays public key for an address.

参数:

  • <address>:账户地址
  • <password>:账户密码文件路径

示例(同时演示保险库用法):

ethstore public 00e63fdb87ceb815ec96ae185b8f7381a0b4a5ea account_password.txt --vault vault_name --vault-pwd vault_password.txt

输出(64 字节公钥 hex):

0x84161d8c05a996a534efbec50f24485cfcc07458efaef749a1b22156d7836c903eeb39bf2df74676e702eacc4cfdde069e5fd86692b5ef6ef81ba906e9e77d82

源码视角:public 解密私钥后重建 KeyPair,返回其公钥(safe_account.rs)。注意示例中账户位于 vault 内:CLI 先用 --vault-pwd 打开对应保险库,再定位 StoreAccountRef::vault(&name, address) 完成操作(main.rs)。

五、vault 保险库命令实战

vault 是 ethstore 提供的“账户二次分组加密”机制:vault 自身是一个有独立密码的加密容器(目录内包含 vault.json 元数据文件,见 vault.rs),vault 内每个账户的元数据(地址、name、meta)额外用 vault 密码加密存储(metacrypto 字段,见 safe_account.rs)。账户默认位于根目录(root),可整体搬入/搬出 vault。

5.1 list-vaults — 列出所有保险库

List vaults.

示例:

ethstore list-vaults

输出:

vault1
vault2
vault3

源码视角:遍历根目录下所有包含 vault.json 文件的子目录并返回其目录名(disk.rs)。

5.2 create-vault <vault> <password> — 创建保险库

Create new vault.

参数:

  • <vault>:保险库名称,只能包含字母、数字、空白、短横线 - 和下划线 _
  • <password>:vault 密码文件路径

示例:

ethstore create-vault vault3 vault3_password.txt

输出:

OK

源码视角:vault 名称校验在 check_vault_name 中完成——只允许字母数字、空白、-、_,禁止 .、*、/、\ 等文件系统特殊字符,以防止目录穿越(vault.rs)。创建时会在 vault 目录内生成 vault.json:先用 Keccak256 对密码做哈希,再用 AES-128-CTR + PBKDF2 加密该哈希作为校验依据(vault.rs)。vault.json 的加密字段结构示例(来自源码测试数据):

{"crypto":{"cipher":"aes-128-ctr","cipherparams":{"iv":"758696c8dc6378ab9b25bb42790da2f5"},"ciphertext":"54eb50683717d41caaeb12ea969f2c159daada5907383f26f327606a37dc7168","kdf":"pbkdf2","kdfparams":{"c":1024,"dklen":32,"prf":"hmac-sha256","salt":"3c320fa566a1a7963ac8df68a19548d27c8f40bf92ef87c84594dcd5bbc402b6"},"mac":"9e5c2314c2a0781962db85611417c614bd6756666b6b1e93840f5b6ed895f003"}}

5.3 change-vault-pwd <vault> <old-pwd> <new-pwd> — 修改保险库密码

Change vault password.

参数:

  • <vault>:已存在保险库名称
  • <old-pwd> / <new-pwd>:旧/新 vault 密码文件路径

示例:

ethstore change-vault-pwd vault3 vault3_password.txt new_vault3_password.txt

输出:

OK

源码视角:CLI 先 open_vault 校验旧密码,再调用 change_vault_password(main.rs)。底层 VaultKeyDirectory::set_key 的实现很讲究:先在 vault_temp_N 临时目录里用新密码重建所有账户文件,逐个 rename 覆盖回原 vault,最后替换 vault.json 并删除临时目录(vault.rs),避免中途失败留下半加密状态。EthMultiStore 层还会自动“关闭再打开”vault 以刷新内存态(ethstore.rs)。

5.4 move-to-vault <address> <vault> <password> — 账户搬入保险库

Move account to vault from another vault/root directory.

参数:

  • <address>:账户地址
  • <vault>:目标 vault 名称
  • <password>:目标 vault 的密码文件路径
  • [--vault VAULT]:账户当前所在 vault(若在 vault 中)
  • [--vault-pwd VAULTPWD]:当前 vault 的密码文件路径(若设置了 --vault)

示例:

# 账户目前在根目录 → 搬入 vault3
ethstore move-to-vault 00e63fdb87ceb815ec96ae185b8f7381a0b4a5ea vault3 vault3_password.txt
# 账户目前在 vault3 → 搬到 vault1
ethstore move-to-vault 00e63fdb87ceb815ec96ae185b8f7381a0b4a5ea vault1 vault1_password.txt --vault vault3 --vault-pwd vault3_password.txt

输出:

OK
OK

源码视角:move-to-vault 先根据 --vault/--vault-pwd 确定账户当前引用(root 或指定 vault),用目标 vault 密码打开目标 vault,再调用 change_account_vault(main.rs)。底层逻辑:读取账户 → 插入目标 vault → 从原位置删除 → 重载缓存(ethstore.rs),同时会在账户 meta 中自动写入/移除 {"vault":"..."} 标记(ethstore.rs 的测试断言可见该行为)。

5.5 move-from-vault <address> <vault> <password> — 账户搬出保险库

Move account to root directory from given vault.

参数:

  • <address>:账户地址
  • <vault>:账户当前所在 vault 名称
  • <password>:该 vault 的密码文件路径

示例:

ethstore move-from-vault 00e63fdb87ceb815ec96ae185b8f7381a0b4a5ea vault1 vault1_password.txt

输出:

OK

源码视角:与 move-to-vault 对称,先打开 vault,再调用 change_account_vault(SecretVaultRef::Root, ...) 把账户搬回根目录(main.rs)。搬回根目录时 disk.rs 会从 meta 中剥离 vault 标记,写回普通 V3 密钥文件。

六、密钥加密格式与原理纵深

6.1 账户密钥文件的加密结构

每个账户对应一个 V3 密钥文件,其核心是 crypto 字段(定义见 account/crypto.rs):

字段 说明
cipher 加密算法,ethstore 使用 aes-128-ctr(带随机 16 字节 iv)
ciphertext 私钥密文
kdf 密钥派生函数,支持 pbkdf2(默认)与 scrypt
mac 消息认证码,32 字节

加密流程(Crypto::with_secret,crypto.rs):

  1. 生成随机 32 字节 salt 与 16 字节 iv;
  2. 用 PBKDF2-HMAC-SHA256(迭代次数来自 KEY_ITERATIONS,默认 10240)从密码派生出 32 字节 DK,前 16 字节作为 AES 密钥、后 16 字节用于 MAC;
  3. AES-128-CTR 加密私钥得到 ciphertext;
  4. mac = KECCAK(DK[16..31] ++ ciphertext)。

解密时先按 KDF 参数重新派生密钥,校验 MAC 是否一致——不一致直接返回 InvalidPassword(crypto.rs),因此密码错误绝不会解出“错误但可用”的私钥。

6.2 存储后端:根目录与保险库的目录布局

accounts_dir 模块抽象了三种存储后端:

  • RootDiskDirectory:根密钥库目录,直接存放 V3 密钥文件;
  • VaultDiskDirectory:vault 目录,内含 vault.json 与若干 VaultKeyFile(账户文件带 metacrypto 字段);
  • MemoryDirectory:内存目录,主要用于单元测试(如 ethstore.rs 的测试辅助函数)。

DiskDirectory::files() 在扫描时会跳过隐藏文件(以 . 开头)以及 thumbs.db、address_book.json、dapps_policy.json、vault.json 等白名单文件(disk.rs),避免把非密钥文件误当成账户。

6.3 缓存与刷新机制

EthMultiStore 内部维护账户内存缓存(BTreeMap<StoreAccountRef, Vec<SafeAccount>>)。默认关闭磁盘自动刷新(refresh_time 为 u64::max_value() 秒),因此只感知当前实例创建/导入的账户;可通过 set_refresh_time 开启按间隔轮询目录变化(ethstore.rs)。由于同一地址可能对应多把密钥,缓存值设计为 Vec<SafeAccount>,允许同一地址多个不同密码的账户并存——ethstore.rs 的 multistore_should_be_able_to_have_the_same_account_twice 测试专门验证了这一点。

6.4 CLI 与库 API 的映射关系

CLI 的每个命令都只是对 SimpleSecretStore / SecretStore trait 的薄封装(secret_store.rs):

CLI 命令 底层 API 关键文件
insert insert_account ethstore.rs
change-pwd change_password ethstore.rs
list accounts + 过滤 main.rs
import import_accounts import.rs
import-wallet PresaleWallet + insert_account presale.rs
sign sign safe_account.rs
public public safe_account.rs
create-vault / change-vault-pwd / move-to-vault / move-from-vault create_vault / change_vault_password / change_account_vault vault.rs

若要在自己的 Rust 程序中直接使用 ethstore,可以像 tests/api.rs 一样引入 ethstore::{EthStore, SimpleSecretStore, SecretVaultRef},以 RootDiskDirectory 或 MemoryDirectory 作为后端打开存储,然后调用上述 trait 方法完成账户全生命周期管理。

七、常见使用场景小结

  1. 创建账户:ethstore insert <secret> <password-file>,输出地址即账户标识;
  2. 从 geth 迁移:ethstore import(默认从 geth 目录导入到 parity 目录),也可用 --src / --dir 指定任意路径;
  3. 找回预售钱包密码:先用 brutedist 之类工具生成候选密码列表,再 ethstore find-wallet-pass ethwallet.json passwords.txt;
  4. 分层隔离密钥:create-vault 建 vault → move-to-vault 搬入账户 → 用 --vault + --vault-pwd 对 vault 内账户执行 sign、public、remove 等操作;
  5. 离线签名与审计:sign 输出 65 字节签名,可用账户地址与消息做 verify_address 校验(测试见 tests/api.rs)。

八、总结

ethstore 通过 14 个 CLI 命令覆盖了以太坊密钥管理从创建、导入、签名到 vault 分组隔离的完整链路。其设计要点可归纳为:密码永不落盘、以文件形式传入;账户私钥始终以 AES-128-CTR + PBKDF2/Scrypt 加密存储,MAC 校验保证密码错误必然失败;vault 通过独立密码与 metacrypto 字段实现二次加密,账户可在根目录与各 vault 之间自由迁移。深入阅读 accounts/ethstore/src 下的实现与 tests/api.rs 测试,可以为你在此基础上扩展自己的密钥管理工具提供完整的参考。

登录后查看全文
parity-ethereum