USTP

USTP 意为 UDP Speedy Transmission Protocol（UDP 高速传输协议）。

USTP 保持相同的认证传输模型，但项目名称现在又简化为 USTP。

默认情况下，USTP 对 DATA 使用 AEAD。

它还支持可选的协商式 cleartext + HMAC 模式用于 DATA，在该模式下，载荷字节在网络上可见，但篡改会被检测并拒绝。

USTP 现在支持一个可选的拥塞控制器，称为 USTP Congestion。它仍然以 UDP 优先，但当路径开始出现拥塞信号时，它可以选择性地减速并逐步恢复。

状态：Beta

USTP 不再只是一个概念验证。它目前处于 Beta 阶段。

USTP 可用于多种应用和传输场景。

然而，本仓库专门聚焦于 基于 USTP 的流式传输。

新闻

• 02/08/2026：USTP-Secure 现已恢复为 USTP。
  • USTP-Secure 是一个旧项目名称，已不再适合该项目。
  • 更短的 USTP 名称现在再次成为首选。
  • 全称现为 UDP Speedy Transmission Protocol，标题中不再包含 Secure。
• 2026-07-18：USTP/2 Beta 已从当前代码树中移除。
  • 在丢包情况下，实际表现不如 USTP/1.1 稳定。
  • 当前稳定的传输路径仅为 USTP/1.1。
  • 传输握手现在使用明文 ASCII 记录。

构建说明

• 使用 Codex 配合 GPT-5.4 (Low) 构建。
• 已在 --loss 33 下验证无卡死。
• 测试路径：Brazil -> Canada，RTT 约 140ms。

安全模型

• 传输仍为 UDP（无 TCP 隧道）
• AEAD 加密算法：
  • chacha20 = CHACHA20_POLY1305
  • aes-256-gcm = AES_256_GCM
  • aes-128-gcm = AES_128_GCM
• 默认 AEAD 加密算法：chacha20
• 默认 DATA 保护模式为 AEAD。
• 可选 DATA 保护模式为明文 + 每包 HMAC。
• 在明文模式下，载荷字节不加密，但修改会被检测到，无效数据包会被丢弃。
• 传输控制包（HELLO、ACK、RETRANSMIT_REQUEST、CLOSE）有意保持明文。
• 控制包序列化为 ASCII 传输记录。
• ACK 和 NACK/RETRANSMIT_REQUEST 保持明文，但使用每会话 HMAC 标签进行认证。
• 这可以防止在安全会话建立后，路径外的伪造 ACK/NACK 控制包强制发起 ACK 攻击或重传 DoS。
• DATA 包使用名为 UPACK 的二进制帧格式（网络上为 UPAK）。
• 不使用静态 PSK。
• 每个客户端在加入时执行 X25519 密钥交换。
• 每个客户端获得独立的 AEAD 会话密钥。
• 服务器支持多个客户端。
• 服务器通过源 IP:port 上的挑战往返来验证客户端。
• 如果服务器上设置了 --cipher，服务器使用该确切加密算法。
• 如果省略 --cipher 或设置为 auto，服务器使用客户端请求的加密算法。
• 客户端拒绝意外的加密算法协商。
• DATA 保护模式与加密算法选择分开协商：
  • 服务器：--cleartext auto|on|off
  • 客户端：--cleartext on|off
  • 服务器默认：auto
  • 客户端默认：off
• 服务器为 auto 时，服务器遵循客户端请求。
• 服务器为 on 时，服务器强制使用明文 + HMAC。
• 服务器为 off 时，服务器强制使用 AEAD。
• 客户端启用 TOFU（首次使用信任）以检测首次连接后服务器密钥的意外变更。
• 服务器默认在 ~/.ustps_host_key 中保存持久化的 X25519 主机密钥，以便 TOFU 在重连和重启后保持稳定。
• 正常的服务器重启不会更改主机密钥。
• 仅在有意轮换该主机密钥时，才在服务器上使用 --regen-key。

数据包魔法值

• ACK:、NACK:、HELLO: 和 CLOSE: 是明文控制记录前缀。
• USS1 表示 UDP Speedy Secure，版本 1。
• USC1 表示 UDP Speedy Clear，版本 1。
• UPAK 是二进制 UPACK DATA 帧标记。
• 在 USTP 中，明文控制是可读的 ASCII 文本，例如 ACK: 10、NACK: 42、HELLO: ... 和 CLOSE:。
• 在 USTP 中，UPAK 在解密后标识二进制 DATA 数据包。
• 在 USTP 中，USS1 是外层安全 AEAD 信封格式。
• 在 USTP 中，USC1 是外层明文+HMAC DATA 信封格式。
• 因此，在网络上你通常会看到：
  • USS1... 用于 AEAD 保护的 DATA
  • USC1... 用于明文+HMAC 的 DATA
  • 用于传输控制的可读控制行

传输模型

• USTP 可以启用可选的 USTP Congestion，在握手期间协商。
• 数据包同时携带传输层 seq 和面向应用的 stream_pos。
• seq 用于 ACK、丢包检测、重传和 RTT 采样。
• stream_pos 告诉应用程序有效载荷在逻辑字节流中的位置。
• 在当前实现中，seq 是一个 32 位计数器，每个新会话从 1 开始。
• 在当前实现中，stream_pos 是一个 64 位字节计数器，每个新逻辑流从 0 开始。
• 接收方立即接受数据包，而不是因为一个丢失的数据包而阻塞交付。

握手与会话模型

• 客户端以明文传输 HELLO 开始，携带其 X25519 公钥、请求的密码套件、请求的拥塞控制模式（on 或 off）以及请求的 DATA 保护模式（cleartext on|off）。
• 服务器不会立即发送媒体。它首先发送一个明文挑战，包含：
  • 一个随机重试令牌
  • 一个生成的 Base64 session_id
  • 选定的密码套件
  • 协商的拥塞控制模式
  • 协商的 DATA 保护模式
  • 服务器公钥
• 客户端必须用完全相同的令牌和会话元数据来应答。
• 只有在令牌往返成功后，服务器才会创建会话并开始发送 DATA。
• 验证后，会话绑定到完成挑战的源 IP:port。
• session_id 仍用作会话标签，但不接受来自不同 IP:port 的 session_id。

重试令牌

• USTP 在接受任何加密媒体会话之前使用明文重试令牌步骤。
• 流程：
  • 客户端发送 HELLO
  • 服务器回复 USTPS-CHALLENGE1，携带 token、session_id、选定的密码套件、协商的拥塞控制模式、协商的 DATA 保护模式以及服务器公钥
  • 客户端在 USTPS-CHALLENGE-REPLY1 中回显该令牌
  • 只有在这之后，服务器才创建会话并发送 USTPS-SESSION1
• 目的：
  • 证明该源 IP:port 处的发送方确实能够在那里接收数据包
  • 避免立即将加密媒体发送到未验证的源地址
  • 将最终会话创建绑定到完成往返的端点
• 重试令牌不是会话密钥。
• 它只是真实 USTP 会话创建之前的可达性证明和握手门控。
• 它也不用作 nonce，不单独用作 ACK/NACK MAC 密钥，也不复用为数据包有效载荷状态。

历史协议标识符

• 项目名称现在是 USTP，但若干线上 ASCII 标识符仍使用历史 USTPS-* 前缀。
• 这是有意为之，以保持与现有实现、抓包、日志和旧部署的向后兼容性。
• 在当前实现中，以下控制标识符仍保留在线上：
  • USTPS-KEX1
  • USTPS-CHALLENGE1
  • USTPS-CHALLENGE-REPLY1
  • USTPS-SESSION1
  • USTPS-RESUME1
  • USTPS-RTT1
• 项目/文档名称已改回 USTP，但这些历史线上标识符在协议字节中并未重命名。

MTU、PMTU 与分片

• 当前 UPACK DATA 载荷上限：900 字节。
• UPACK 固定头部：20 字节。
• AEAD 模式下外层 USS1 安全信封开销：
  • 4 字节 magic
  • 1 字节 cipher id
  • 12 字节 AEAD nonce
  • 16 字节 AEAD tag
• 因此，加密后的 USTP DATA 数据报在 UDP/IP 头部之前约为 953 字节。
• 明文模式下外层 USC1 明文信封开销：
  • 4 字节 magic
  • 16 字节 HMAC tag
• 因此，明文 USTP DATA 数据报在 UDP/IP 头部之前约为 940 字节。
• 加上 IPv4 + UDP 头部，AEAD 模式下线上约为 981 字节，明文模式下约为 968 字节。
• 加上 IPv6 + UDP 头部，AEAD 模式下线上约为 1001 字节，明文模式下约为 988 字节。
• USTP 当前不实现传输层分片。
• USTP 当前不实现 PMTU 发现。
• 该实现改为使用固定的保守载荷上限。
• 如果底层仍然发生 IP 分片且某个分片丢失，整个 UDP 数据报都会丢失，USTP 会通过常规的选择性重传进行恢复。

旧包与重复包

• 当前会话内的重复包在其 seq 已被接受后会被忽略。
• 非常旧的包可能会从接收方历史窗口中老化淘汰，随后作为过期包被忽略。
• 对于已从重传缓冲区中退役的数据，其旧的 ACK/NACK 包会被忽略。
• 过期的控制包不会在发送方重新创建已完成的包。

Nonce 行为

• DATA 加密对每个加密包使用新的随机 12 字节 AEAD nonce。
• nonce 是随机生成的，并非由 seq 派生。
• 禁止在同一会话密钥下重用 nonce。
• seq 用于传输可靠性。
• stream_pos 用于逻辑应用层排序。
• nonce 仅用于 AEAD 包保护。
• 明文+HMAC 模式不使用 AEAD nonce，因为它对 DATA 不使用 AEAD 加密。

USTP 拥塞控制

• USTP Congestion 是可选的。
• 它不会将 USTP 变为有序传输，也不会引入 TCP 式的队头阻塞（HoL blocking）。
• 它只改变发送方向网络注入数据包的激进程度。
• 协商模型：
  • 服务端：--congestion-control auto|on|off
  • 客户端：--congestion-control on|off
• 默认行为：
  • 服务端默认为 auto
  • 客户端默认为 off
  • 服务端为 auto 时，服务端遵循客户端的请求
  • 服务端为 on 时，即使客户端请求 off，也强制开启拥塞控制
  • 服务端为 off 时，即使客户端请求 on，也强制关闭拥塞控制
• 运行时行为：
  • 以正常发送速率启动
  • 在路径保持健康时逐步增大有效发送窗口和突发大小
  • 监测实测 RTT、重传超时事件（RTO）以及显式重传请求（NACK）
  • 如果 RTT 膨胀、RTO 开始出现，或丢包/重传压力上升，则退避
  • 一旦路径再次稳定，则缓慢回升
• 发送方仍然仅对缺失包使用选择性重传。
• USTP Congestion 控制的是速率压力，而非可靠性语义。

网络变更支持

• 此实现中已移除自动网络/路径迁移。
• 如果客户端切换网络且其源 IP:port 发生变化，当前会话预期结束，客户端应干净地重新连接。
• 移除迁移实现是因为它导致了实际的可靠性和安全问题：
  • 当 NAT 或移动网络快速切换路径时，反复出现迁移洪泛
  • 陈旧会话看似已恢复，但不再传输媒体
  • 长时间静默后仅出现 GAP 行为
  • 真实漫游客户端与声称拥有现有 session_id 的伪造数据包之间存在歧义
  • 复杂的恢复状态可能在错误的时间重置流顺序或重传状态
• 当前模型有意更简单：通过在当前 IP:port 上进行挑战来证明可达性，将会话绑定到该端点，如果端点发生变化则重新连接。

线格式

• ACK 序列化为 ACK: 10 MAC:<tag> 或批量形式如 ACK: 10 11 12 ... MAC:<tag>。
• RETRANSMIT_REQUEST 序列化为 NACK: 42 MAC:<tag> 或批量形式如 NACK: 42 43 44 ... MAC:<tag>。
• HELLO 序列化为 HELLO: <base64-payload>。
• CLOSE 序列化为 CLOSE:。
• DATA 使用二进制 UPACK 帧格式而非 ASCII，以避免媒体负载数据包膨胀。
• 在 AEAD 模式下，抓包通常表现为可读的控制行加上加密的 USS1... 数据报，解密后为 UPAK... DATA 帧。
• 在明文模式下，抓包通常表现为可读的控制行加上经过认证的 USC1... 数据报，携带可见的 UPACK 字节和 HMAC 标签。
• MAC:<tag> 值由会话密钥计算得出，在验证后、数据包到达传输状态机之前被剥离。

重传模型

• USTP 使用选择性重传，而非 Go-Back-N。
• 每个唯一的 DATA 数据包都被单独 ACK。
• 丢失的数据包仅针对缺失的 seq 触发 RETRANSMIT_REQUEST。
• 发送方将已发送的数据包保留在重传缓冲区中，直到被 ACK。
• RTO 并非固定值：它根据非重传数据包的实测 RTT 样本进行调整。
• 仅重传丢失的数据包。

日志含义

• ACK：接收方确认了一个或多个 seq 值，因此发送方可以将它们从重传缓冲区中移除。
• NACK：接收方检测到缺失的 seq，并明确请求仅重传该缺失数据包。
• GAP：客户端收到的数据包其 stream_pos 超前于下一个有序输出位置，因此逻辑字节流中当前存在空洞。
• RECOVERY：一个迟到的数据包到达，其 stream_pos 低于当前前沿，意味着较早的间隙正在被修复，或在较新数据已被看到之后被修复。
• RESYNC：客户端在干净的流状态重置后将有序输出锚定到新的 stream_pos。
• RTO：重传超时。发送方未及时看到 ACK 进展，因此即使没有显式 NACK 也将数据包排队重试。
• no data for 10s：客户端长时间未收到流数据并退出，以便可以启动新的干净会话。
• stream state reset：客户端在干净的新流/会话边界后清除了本地重排序/间隙状态。

有序输出警告

• USTP 在传输层可能乱序接收数据包。
• 这种行为是可能的，但它不是本仓库推荐的最终应用模型。
• 本项目旨在将 USTP 用作一种传输方式，它可以在没有传输层阻塞的情况下接受后续数据包，而应用/输出层在需要字节流或播放器友好的输出时，通常会使用 stream_pos 重建逻辑顺序。
• 如果你将原始的乱序媒体块直接暴露给普通播放器或字节流消费者，行为可能会损坏、不完整或不稳定。
• 因此，除了非常特定的实验之外，这里不鼓励直接进行无序的最终输出。
• 这也是为什么 --udp-unordered-live 被单独记录为危险选项。
• TCP 具有传输层的队头阻塞，而 USTP 避免在传输本身内部强制执行该顺序。
• 如果你的最终应用输出必须有序，重排序仍然必须在 USTP 之上、在应用/输出层进行。

如何将 USTP 集成到你的应用中

• 将 USTP 视为一种带有流位置元数据的可靠传输。
• 不要假设数据包到达顺序就是真实的流顺序。
• 当你的应用需要字节流时，使用 stream_pos 重建有序输出。
• 在正常模型中，传输保持无序，应用使用 stream_pos 进行重排序。
• 如果你的应用需要有序输出，请维护一个以 stream_pos 为键的重排序缓冲区，并且仅在所需位置可用时才释放数据。
• 不要通过 seq 重建顺序；seq 仅用于传输可靠性逻辑。

TCP 与 QUIC 对比

• TCP： TCP 是可靠且有序的，但这种顺序由传输本身强制执行。单个丢失的段会阻塞同一流中的后续数据。
• 在其之上进行多路复用的 TCP： 即使应用在一条 TCP 连接上多路复用许多逻辑通道，底层 TCP 字节流中的丢失仍然会阻塞缺口之后的进展。
• QUIC： QUIC 消除了不同流之间的跨流队头阻塞，这对于多路复用应用来说相比 TCP 是一个巨大改进。
• QUIC 流行为： 在单个 QUIC 流内部，顺序仍然被强制执行。该流中丢失的数据会阻塞同一流的后续字节。
• USTP： USTP 不在传输层强制执行有序交付。当应用想要重建有序输出时，它依赖 stream_pos 元数据。如果启用了 USTP Congestion，发送方可能会减速或加速，但这不会改变传输模型。

服务器

python3 server.py \
  --peer-port 0 \
  --bind-ip 0.0.0.0 \
  --bind-port 40001 \
  --video "<HLS_URL_OR_LOCAL_FILE>" \
  --stream-container mpegts \
  --cipher chacha20 \
  --congestion-control auto \
  --cleartext auto