parity-ethereum ethstore 密钥管理工具完全指南:命令用法、保险库机制与源码原理
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):
- 生成随机 32 字节
salt与 16 字节iv; - 用 PBKDF2-HMAC-SHA256(迭代次数来自
KEY_ITERATIONS,默认 10240)从密码派生出 32 字节 DK,前 16 字节作为 AES 密钥、后 16 字节用于 MAC; AES-128-CTR加密私钥得到ciphertext;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 方法完成账户全生命周期管理。
七、常见使用场景小结
- 创建账户:
ethstore insert <secret> <password-file>,输出地址即账户标识; - 从 geth 迁移:
ethstore import(默认从 geth 目录导入到 parity 目录),也可用--src/--dir指定任意路径; - 找回预售钱包密码:先用
brutedist之类工具生成候选密码列表,再ethstore find-wallet-pass ethwallet.json passwords.txt; - 分层隔离密钥:
create-vault建 vault →move-to-vault搬入账户 → 用--vault+--vault-pwd对 vault 内账户执行sign、public、remove等操作; - 离线签名与审计:
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 测试,可以为你在此基础上扩展自己的密钥管理工具提供完整的参考。