SPECIFICATION

第 7 章安全与加密

7.1 安全模型

DTP 实现必须提供端到端加密。安全模型必须满足以下不变量：

仅目标 iFay 实例必须能够解密接收到的 Payload。
FayGer 运行时环境不得在任何情况下访问明文数据。
中间网络节点不得读取 Payload 明文。
DTP 实现不得自行管理加密密钥。

7.2 加密范围

加密范围必须严格限定于 LogicalFrame 的 Payload。

7.2.1 必须加密的内容

以下数据必须加密：

LogicalFrame 的 payload 字段（即 Fragment 的 data 字段以及（若以 Frame 方式承载的）RequestFrame、ResponseFrame、ControlFrame 的内容）。

7.2.2 不得加密的内容

以下数据不得加密，必须以明文传输：

LogicalFrame 的 header（包括 protocolVersion、frameType、fragmentId、agreementId、originTimestamp、dagDependencies、encryptionMetadata、sequenceNumber）。

加密元数据本身不得加密，以使接收方能在解密前确定解密参数。

7.3 密钥管理

7.3.1 密钥来源

DTP 实现必须使用 CAP 预协商的密钥。具体要求：

CAP 必须在连接建立阶段完成身份验证与密钥交换。
DTP 实现必须使用 CAP 提供的 sessionKey 进行 Payload 加密/解密。
DTP 实现不得自行生成、协商或交换加密密钥。

7.3.2 CAPContext 接口

DTP 实现必须通过以下接口接收 CAP 提供的上下文：

interface CAPContext {
  identity: string;
  sessionKey: Uint8Array;
  verified: boolean;
}

字段	规范性要求
`identity`	必须为对端身份标识
`sessionKey`	必须为 CAP 协商出的会话密钥的字节序列
`verified`	必须反映 CAP 验证状态

7.3.3 CAP 前置条件

DTP 实现必须在开始数据传输前验证 CAPContext：

如 verified === false，必须拒绝发送任何数据帧并返回 KEY_NOT_READY 错误（2002）。
如 sessionKey 为空或长度无效，必须返回 KEY_NOT_READY 错误。
协商帧（Request_Frame、Response_Frame）的传输同样受此前置条件约束。

7.4 加密元数据

每个 LogicalFrame 的帧头必须携带 EncryptionMetadata：

interface EncryptionMetadata {
  algorithm: string;
  keyVersion: number;
}

7.4.1 算法标识符

algorithm 字段必须为加密算法的标识字符串。应使用以下标准化命名之一：

标识符	算法	状态
`"AES-256-GCM"`	AES-256 in Galois/Counter Mode	推荐
`"ChaCha20-Poly1305"`	ChaCha20 with Poly1305	推荐
`"AES-128-GCM"`	AES-128 in Galois/Counter Mode	可使用

实现必须至少支持 AES-256-GCM 与 ChaCha20-Poly1305 中的一种。推荐同时支持两种以增强互操作性。

实现不得使用：

ECB 模式（不安全）
无认证的加密模式（CBC、CTR 不带 MAC）
已知存在弱点的算法（DES、3DES、RC4）

7.4.2 密钥版本号

keyVersion 必须为非负整数，用于支持密钥轮换：

当 CAP 触发密钥轮换时，新密钥的 keyVersion 必须严格大于上一个版本。
接收方必须使用 keyVersion 选择对应的解密密钥。
实现应维护至少一个旧密钥版本以支持飞行中（in-flight）的 Fragment。

7.5 加密往返一致性

实现必须满足以下加密往返一致性属性：

使用正确密钥（与发送方使用的密钥匹配）加密后再解密，必须产生与原始 Payload 字节级相同的输出。
使用错误密钥解密必须失败，必须返回 DECRYPTION_FAILED 错误（2001）。
解密失败时，实现不得返回部分解密结果或损坏的数据。

7.6 终端侧解密

当终端作为接收方时（数据注入场景）：

DTP_Slave 必须使用终端在 CAP 连接建立阶段提交的密钥进行解密。
该密钥必须与终端在 CAP 中提交的私钥/会话密钥对应。
终端不得接受任何其他密钥的解密结果。

7.7 解密失败处理

实现必须按以下规则处理解密失败：

单次解密失败：丢弃帧，发送 DECRYPTION_FAILED 错误通知（2001）。
连续解密失败超过阈值（实现定义，推荐为 3 次）： a. 应触发 CAP 重新密钥交换。 b. 应通知上层应用安全异常。
实现不得在多次解密失败后无限重试同一帧。

7.8 安全威胁防护

实现必须通过协议设计防护以下威胁：

威胁	防护机制
中间人窃听	Payload 端到端加密
FayGer 窥探	Payload 加密，FayGer 仅可见密文
密钥泄露	密钥版本号机制支持密钥轮换
身份伪造	委托给 CAP 验证
重放攻击	序列号单调递增 + 会话绑定
帧篡改	使用认证加密（AEAD）算法

7.9 重放保护

实现必须通过以下机制防护重放攻击：

序列号单调递增：接收方必须拒绝序列号小于或等于已确认最高序列号的帧（除非处于续传场景）。
会话绑定：序列号空间必须与具体会话绑定。新会话必须重置序列号。
AEAD 认证：加密算法必须提供消息认证（GCM、Poly1305 等）。

7.10 元数据隐私

实现应注意：帧头中的明文元数据可能泄露以下信息：

通信对端身份（通过 agreementId 关联）
通信时间模式（通过 originTimestamp 与 sequenceNumber）
数据传输频率（通过帧之间的时间差）

实现可通过以下方式增强元数据隐私：

启用流量填充（实现定义）。
使用混淆传输层（如基于 TLS 1.3 的 ECH）。

但本规范 不要求 实现提供元数据隐私保护。

第 7 章 安全与加密