P2P 与分布式存储 / 系统课时
校验 v2 Piece Layers 的哈希
校验 v2 Piece Layers 的哈希
BitTorrent v2 不再依赖 v1 的连续 SHA-1 Piece 哈希列表,而是使用 SHA-256 Merkle 树验证文件内容。本课通过一个四块文件的例子,说明 Piece Layers 如何关联文件根哈希、怎样验证下载数据,以及何时必须获取额外的 Merkle 证明。
学习目标
- 理解 v2 文件根哈希、Piece Layers 和数据块哈希之间的关系。
- 使用 SHA-256 构造并验证一个最小 Merkle 树。
- 区分完整 Piece Layers 校验、单个 Piece 校验和 v1 的校验方式。
Piece Layers 存储的是什么
在 BEP 52 中,v2 使用每个文件独立的 SHA-256 Merkle 树。叶子层对应最多 16 KiB 的数据块;内部节点通过连接两个 32 字节子节点哈希并再次计算 SHA-256 得到。文件树中的 pieces root 保存该文件的根哈希。
当 piece length 大于 16 KiB 时,一个 Piece 对应多个叶子。Piece Layers 存放的是指定 Piece 层级上的哈希,而不是文件内容,也不是所有内部节点。对于大于一个 Piece 的文件,这些哈希按 Piece 顺序连接成二进制字符串,放在种子顶层的 piece layers 字典中,以对应文件的 32 字节 pieces root 为键。
例如,一个文件长度为 65536 字节,piece length = 32768 字节,则每个 Piece 包含两个 16 KiB 叶块,文件共有两个 Piece。Piece Layers 中需要两个 32 字节 Piece 哈希,共 64 字节。
| 层级 | 内容 | 数量 |
|---|---|---|
| 叶子层 | SHA-256(16 KiB 数据块) | 4 |
| Piece 层 | 每两个叶子哈希合并 | 2 |
| 文件根 | 两个 Piece 哈希合并 | 1 |

实际协议还要求对不足完整树容量的部分使用规定的零哈希进行填充。空子树的哈希必须按树层级递推生成,不能简单把任意缺失节点当作 32 个零字节。文件长度与 Piece 长度决定树的实际结构。
先验证 Piece Layers 与文件根是否一致
收到 .torrent 元数据后,不能直接信任 piece layers 的内容。客户端应先从已经验证的 info 字典取得文件长度、piece length 和 pieces root,再验证对应 Piece 哈希是否能够重建同一个文件根。
对上面的四叶块示例,校验顺序为:
- 读取文件长度 65536 和 Piece 长度 32768,计算 Piece 数量为 2。
- 根据文件的
pieces root找到对应 Piece Layers 条目,确认其长度为 64 字节。 - 将其拆分为
H01和H23两个 32 字节哈希。 - 计算
SHA256(H01 || H23),与pieces root逐字节比较。 - 不一致则拒绝该 Piece Layers 条目,不把其中哈希作为可信下载校验依据。
下面使用 Python 3 标准库演示这个完整的双 Piece 情况。示例通过固定内容生成四个 16 KiB 数据块,再构造 Piece Layers 和文件根,最后模拟下载内容被篡改。
import hashlib
BLOCK_SIZE = 16 * 1024
def sha256(data: bytes) -> bytes:
return hashlib.sha256(data).digest()
def parent(left: bytes, right: bytes) -> bytes:
# Merkle 内部节点使用两个原始32字节摘要拼接
return sha256(left + right)
def main():
blocks = [bytes([i]) * BLOCK_SIZE for i in range(4)]
leaves = [sha256(block) for block in blocks]
# 每个 Piece 包含两个16 KiB叶块
piece_hashes = [
parent(leaves[0], leaves[1]),
parent(leaves[2], leaves[3]),
]
piece_layers = b"".join(piece_hashes)
pieces_root = parent(*piece_hashes)
recovered = [
piece_layers[i:i + 32]
for i in range(0, len(piece_layers), 32)
]
print("Piece Layers 长度:", len(piece_layers))
print("文件根匹配:", parent(*recovered) == pieces_root)
downloaded = blocks[0] + blocks[1]
downloaded_hash = parent(
sha256(downloaded[:BLOCK_SIZE]),
sha256(downloaded[BLOCK_SIZE:]),
)
print("Piece 0 校验:", downloaded_hash == recovered[0])
tampered = bytearray(downloaded)
tampered[0] ^= 1
bad_hash = parent(
sha256(tampered[:BLOCK_SIZE]),
sha256(tampered[BLOCK_SIZE:]),
)
print("篡改后校验:", bad_hash == recovered[0])
if __name__ == "__main__":
main()预期输出:
Piece Layers 长度: 64
文件根匹配: True
Piece 0 校验: True
篡改后校验: False这里的 pieces_root 是由示例数据构造的可信比较基准。真实客户端必须先验证种子元数据的来源或标识一致性,不能用未经验证的 Piece Layers 自己生成一个根哈希,再把这个根哈希当成可信依据。
下载单个 Piece 时如何校验
当 Piece Layers 已通过文件根验证后,客户端可以直接将下载 Piece 的 Merkle 子树根与对应的 Piece 哈希比较。以 Piece 0 为例,先分别计算其两个 16 KiB 叶块的 SHA-256,再合并为 H01,最后与已验证的 Piece Layers 第一项比较。
如果没有完整且可信的 Piece Layers,只有文件根哈希,则不能只计算单个 Piece 的哈希就宣称通过验证。客户端还需要从 Piece 所在层级到文件根的兄弟节点哈希,即 Merkle 证明。
在四叶块示例中,验证 Piece 0 需要 H23 作为兄弟节点:
- 对下载的 B0、B1 分别计算 SHA-256。
- 合并得到
H01。 - 使用证明中的
H23计算SHA256(H01 || H23)。 - 将结果与可信
pieces root比较。

Merkle 证明不是一组无序哈希。每一级都必须根据节点位置决定拼接顺序,SHA256(left || right) 与 SHA256(right || left) 通常不同。对更大的文件,证明可能包含多个层级的兄弟哈希。
v1 与 v2 的校验粒度差异
v1 在 info.pieces 中保存整个资源按固定 Piece 长度划分后的 SHA-1 摘要,每个 Piece 一个 20 字节哈希。下载端取得完整 Piece 后计算 SHA-1,并与相应位置的摘要比较。多文件资源在 v1 中按逻辑顺序拼接,Piece 可能跨越文件边界。
v2 使用文件独立的 SHA-256 Merkle 树,pieces root 锚定文件内容,Piece Layers 为较大文件提供可直接使用的 Piece 层哈希。协议的基础叶块为 16 KiB,因此还可以通过合适的 Merkle 证明验证更细粒度的数据块。
| 对比项 | v1 | v2 |
|---|---|---|
| 哈希算法 | SHA-1 | SHA-256 |
| 元数据锚点 | 全局 Piece 哈希列表 | 每文件 pieces root |
| 常规 Piece 校验 | 与 info.pieces 对应摘要比较 |
与已验证的 Piece 层哈希比较 |
| 细粒度验证 | 通常需完整 Piece | 可结合 Merkle 证明验证叶块 |
| 多文件边界 | Piece 可以跨文件 | 每个文件独立建树 |
例如,Piece 长度为 256 KiB 时,v1 通常需要收齐这 256 KiB 才能进行对应 Piece 的完整性判断。v2 可以在具备可信证明的条件下验证其中的 16 KiB 叶块,但这不表示每个 v2 客户端都会为每个网络 Block 单独请求或验证证明。
实际实现需要检查的边界
工程实现中,先校验元数据结构,再验证 Piece Layers,最后校验下载数据,可以避免错误哈希污染调度器的已完成状态。
- 单 Piece 文件:文件长度不大于
piece length时,通常不需要独立的 Piece Layers 条目,直接使用文件根进行验证;仍需按 v2 的树构造和填充规则计算。 - 尾部不足 16 KiB:最后一个叶块使用实际数据计算哈希,不能把数据块直接补零到 16 KiB 后再计算 SHA-256;缺失的树节点另按协议的零哈希规则处理。
- Piece 数量与字节长度:对于需要 Piece Layers 的文件,条目长度必须与 Piece 数量乘以 32 字节一致,不能接受多余或缺失摘要。
- 非法树结构:
piece length必须符合 v2 对 16 KiB 整数倍及二的幂倍数的要求,不能随意设置为 24 KiB 或 48 KiB。 - 校验失败后的状态:对应 Piece 应保持未验证状态,丢弃或隔离错误数据,并根据节点来源记录失败信息;不能仅因为网络传输完成就广播 Have。
可以用两个故障测试验证实现:先修改 Piece Layers 的任意一个字节,确认文件根校验失败;再恢复正确的 Piece Layers,只修改下载数据的一个字节,确认元数据校验仍通过,但对应 Piece 数据校验失败。
在生产实现中,还应使用 BEP 52 规定的规范化 bencode、文件树规则、零哈希和 Merkle 证明格式处理任意文件长度。上面的 Python 示例刻意选择完整的四叶块树,用于验证最核心的 SHA-256 拼接关系,不能直接代替完整的 v2 种子解析器。