第4章 Keystore文件格式总览：JSON结构、顶层字段、版本号标识

Keystore 文件本质上是一个 JSON 对象，它把加密后的私钥、解密所需的参数和元数据打包在一起。你可以把它想象成一张“加密身份卡”——卡片本身是明文 JSON，但卡片上的核心信息（私钥）被锁在加密密文里，只有提供正确密码的人才能打开。

4.1 顶层字段概览

一个标准的 Ethererum / 通用加密 Keystore 文件通常包含以下 6 个顶层键名。每个字段都有明确的职责：

4.2 核心结构图解

下面的 SVG 展示了 Keystore JSON 的顶层字段以及 crypto 子对象内部的骨架关系。每个矩形节点代表一个 JSON 键，箭头表示包含或引用关系。

4.3 JSON 实例与层级解读

以下是一个真实 Keystore 文件（版本 3）的缩略结构。注意 crypto 对象内部再嵌套两层参数。

{
  "version": 3,
  "id": "fd6062c4-3b5b-4c8a-bd8e-1e1a7c9f3b23",
  "address": "001d3f1ef827552ae1114027bd3ecf1f086ba0f9",
  "crypto": {
    "cipher": "aes-128-ctr",
    "cipherparams": {
      "iv": "a7c5e1b8c3d4e5f6a7b8c9d0e1f2a3b4"
    },
    "kdf": "scrypt",
    "kdfparams": {
      "dklen": 32,
      "n": 262144,
      "r": 8,
      "p": 1,
      "salt": "ab0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e"
    },
    "mac": "9f2c4e8a7b6d5c3f1e0a9b8c7d6e5f4a3b2c1d0e",
    "ciphertext": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "description": "My primary wallet"
}

4.4 常见误区

• 误区 1：认为 address 字段就是账户的私钥公钥。其实 address 仅是公开索引，真正的私钥藏在 ciphertext 里。
• 误区 2：把 mac（消息认证码）当作密码哈希值。mac 用于验证密码正确性与密文完整性，不是密码本身。
• 误区 3：忽略大小写，将 Crypto 与 crypto 混用导致解析失败。兼容性库必须同时处理两种写法。
• 误区 4：误以为 version 字段表示 Keystore 文件的版本而非格式版本。实际上它只规定 JSON 结构规则，与文件修改版本无关。

4.5 类比：一封数字密信

把 Keystore 文件想象成一封密封信封：version 是信封右上角的“邮件类别码”（航空/快递），address 是收件人姓名，id 是邮单号，description 是便签说明。而信封内的信纸（明文私钥）并非直接可见——它被一张“透明密码纸”包裹，只有用正确的密码喷洒在纸上，字迹才会显现。这个“密码纸”就是 crypto 对象，它包含了墨水配方（kdf 与 cipher）和密文（ciphertext）。

4.6 练习题

1. 以下哪个字段在 Keystore 版本 3 中一定存在且类型为对象？
   A. version  B. crypto  C. description  D. kdfparams
2. 假如你解析到一个 Keystore 文件，version 字段值是 4，而你的解析器只支持版本 3，你应该采取什么行为？
3. True or False：ciphertext 字段存储的是用户设置的密码明文。