保险库格式8规范 —— Cryptomator 加密目录里有哪些文件

保险库不是一个单文件容器

很多加密工具（比如 VeraCrypt）把整个加密空间打包成一个 .hc 或 .hc1 单文件容器。Cryptomator 走的是另一条路：一个保险库就是一个普通文件夹，里面放着加密后的散文件和几个特殊的元数据文件。

这个设计带来的好处很明显：

• 云盘软件能识别增量变更，只同步改动过的那几个密文块，而不是每次拉整个容器。
• 丢失单个文件不会影响整个保险库。
• 可以直接用文件管理器备份保险库目录。

Vault Format 8 目录结构

Cryptomator 从 1.6.0 起默认使用 Vault Format 8，也是唯一支持 Recovery Key 恢复配置文件的版本。如果你还在用 Format 7 或更早的版本，建议升级。

一个 Format 8 保险库目录大致长这样：

我的保险库/
├─ vault.cryptomator           # ← 保险库配置文件（JWT）
├─ vault.cryptomator.DFD9B248.bkup  # vault.cryptomator 的自动备份（可选）
├─ masterkey.cryptomator       # ← 加密的主密钥
├─ masterkey.cryptomator.DFD9B248.bkup  # masterkey 的自动备份（可选）
└─ d/                          # ← 加密文件目录树（实际文件全在这里）
   ├─ BZ/
   │  └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA/
   │     ├─ dirId.c9r          # 目录元信息
   │     ├─ 5TyvCyF255sRtfrIv...83ucADQ==.c9r   # 加密文件
   │     └─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r   # 目录链接文件
   └─ FC/
      └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77/
         └─ 4lmrQYfE_5ETusEkVJlTJrcFzjwxNBymig==.c9r

两个核心配置文件

vault.cryptomator —— 保险库配置（JWT）

这是一个 JWT（JSON Web Token），分三段：header.payload.signature，签名用的是 512 bit 原始 masterkey。解码后可以看到（注意：签名验证需要原始 masterkey，没密码无法验签）：

// header
{
  "kid": "masterkeyfile:masterkey.cryptomator",
  "typ": "JWT",
  "alg": "HS256"
}

// payload
{
  "format": 8,              // Vault Format 版本
  "shorteningThreshold": 220, // 加密文件名在第 N 个字符处开始短名
  "jti": "ce976f7a-...",    // 保险库唯一 UUID
  "cipherCombo": "SIV_GCM"  // AES 模式：SIV_GCM 或 SIV_CTRMAC
}

kid 字段告诉 Cryptomator 去哪里找 masterkey。对于个人密码保险库，它是 masterkeyfile:masterkey.cryptomator；对于 Cryptomator Hub 保险库，它是 hub+// Hub 实例 API 地址。

masterkey.cryptomator —— 加密的主密钥

masterkey 本身是 512 bit：前 256 bit 是 encryption masterkey（加密用），后 256 bit 是 MAC masterkey（完整性校验用）。

但你目录里看到的不是这 512 bit 原始字节——而是被 AES Key Wrap（RFC 3394）用 KEK 包裹后的密文。KEK 由你的密码经 scrypt 派生：

kek = scrypt(password, scryptSalt, cost=32768, blocksize=8, dkLen=32)

masterkey.cryptomator 文件本身是一个 JSON：

{
  "scryptSalt": "QGk...jY=",
  "scryptCostParam": 32768,
  "scryptBlockSize": 8,
  "primaryMasterKey": "QDi...Q==",   // 加密主密钥的 Wrap 形式
  "hmacMasterKey": "L83...Q==",      // MAC 主密钥的 Wrap 形式
  "versionMac": "3/U...9Q="          // HMAC 防降级攻击
}

加密文件放在 d/ 目录树

所有加密后的文件和目录信息都在 d/ 目录下，以两层 hash 路径排列。这棵树里你能看到的密文文件大概长这样：

• *.c9r —— 加密后的文件内容
• dirId.c9r —— 目录的内部标识符（用来在父目录里引用子目录）
• dir.c9r —— 目录本身的元数据（目录名字密文等）

想把这里某个密文文件和它在解锁状态下的明文文件名对应起来，有两个工具：Locate 定位加密文件 和 Decrypt 解密文件名。

Format 8 为什么是分水岭

Format 8 之前（Format 7 及更早版本），配置和密钥派生参数都堆在 masterkey 文件里，没有 vault.cryptomator 这个独立 JWT。Format 8 的改进：

Format 7 的保险库无法使用 Recovery Key 恢复 masterkey 或 vault 配置。 如果你手上还有老保险库，建议新建一个 Format 8 保险库然后把数据搬过去。详情可以看 丢失恢复与保险库抢救。