USTP

USTP means UDP Speedy Transmission Protocol.

USTP keeps the same authenticated transport model, but the project name is now simply USTP again.

By default, USTP uses AEAD for DATA.

It also supports an optional negotiated cleartext + HMAC mode for DATA, where payload bytes are visible on the wire but tampering is detected and rejected.

USTP now supports an optional congestion controller called USTP Congestion. It is still UDP-first, but it can optionally slow down and ramp back up when the path starts showing congestion signals.

Status: Beta

USTP is no longer just a proof of concept. It is currently in the Beta phase.

USTP can be used for many kinds of applications and transports.

This repository, however, is focused specifically on streaming over USTP.

News

• 02/08/2026: USTP-Secure is now back to USTP.
  • USTP-Secure was an old project name and no longer a good fit for the project.
  • The shorter USTP name is now preferred again.
  • The full name is now UDP Speedy Transmission Protocol, without Secure in the title.
• 2026-07-18: USTP/2 Beta was removed from the current tree.
  • Real-world behavior was less stable than USTP/1.1 under loss.
  • The current stable transport path is USTP/1.1 only.
  • The transport handshake now uses plaintext ASCII records.

Build note

• Built with Codex using GPT-5.4 (Low).
• Verified without freezing at --loss 33.
• Test path: Brazil -> Canada with about 140ms RTT.

Security model

• Transport remains UDP (no TCP tunnel)
• AEAD ciphers:
  • chacha20 = CHACHA20_POLY1305
  • aes-256-gcm = AES_256_GCM
  • aes-128-gcm = AES_128_GCM
• Default AEAD cipher: chacha20
• Default DATA protection mode is AEAD.
• Optional DATA protection mode is cleartext + per-packet HMAC.
• In cleartext mode, payload bytes are not encrypted, but modifications are detected and invalid packets are discarded.
• Transport control packets (HELLO, ACK, RETRANSMIT_REQUEST, CLOSE) stay plaintext on purpose.
• Control packets are serialized as ASCII transport records.
• ACK and NACK/RETRANSMIT_REQUEST remain plaintext, but are authenticated with a per-session HMAC tag.
• This prevents off-path forged ACK/NACK control packets from forcing ACK attacks or retransmission DoS after the secure session is established.
• DATA packets use a binary frame format named UPACK (UPAK on the wire).
• No static PSK is used.
• Each client performs an X25519 key exchange when it joins.
• Each client gets a separate AEAD session key.
• Servers support multiple clients.
• The server validates the client with a challenge round-trip on the source IP:port.
• If --cipher is set on the server, the server uses that exact cipher.
• If --cipher is omitted or set to auto, the server uses the cipher requested by the client.
• Clients reject unexpected cipher negotiation.
• DATA protection mode is negotiated separately from cipher choice:
  • server: --cleartext auto|on|off
  • client: --cleartext on|off
  • server default: auto
  • client default: off
• With server auto, the server follows the client request.
• With server on, the server forces cleartext + HMAC.
• With server off, the server forces AEAD.
• TOFU (Trust On First Use) is enabled on the client to detect unexpected server key changes after the first connection.
• The server keeps a persistent X25519 host key in ~/.ustps_host_key by default so TOFU remains stable across reconnects and restarts.
• A normal server restart does not change the host key.
• Use --regen-key on the server only when you intentionally want to rotate that host key.

Packet magic values

• ACK:, NACK:, HELLO:, and CLOSE: are the plaintext control record prefixes.
• USS1 means UDP Speedy Secure, version 1.
• USC1 means UDP Speedy Clear, version 1.
• UPAK is the binary UPACK DATA frame marker.
• In USTP, plaintext control is human-readable ASCII such as ACK: 10, NACK: 42, HELLO: ..., and CLOSE:.
• In USTP, UPAK identifies binary DATA packets after decryption.
• In USTP, USS1 is the outer secure AEAD envelope format.
• In USTP, USC1 is the outer cleartext+HMAC DATA envelope format.
• So, on the wire you normally see:
  • USS1... for AEAD-protected DATA
  • USC1... for cleartext+HMAC DATA
  • readable control lines for transport control

Transport model

• USTP can run with optional USTP Congestion, negotiated during the handshake.
• Packets carry both a transport seq and an application-facing stream_pos.
• seq is used for ACK, loss detection, retransmission, and RTT sampling.
• stream_pos tells the application where the payload belongs in the logical byte stream.
• In the current implementation, seq is a 32-bit counter that starts at 1 for each fresh session.
• In the current implementation, stream_pos is a 64-bit byte counter that starts at 0 for each fresh logical stream.
• The receiver accepts packets immediately instead of blocking delivery behind one missing packet.

Handshake and session model

• The client starts with a plaintext transport HELLO carrying its X25519 public key, requested cipher, requested congestion-control mode (on or off), and requested DATA protection mode (cleartext on|off).
• The server does not send media immediately. It first sends a plaintext challenge containing:
  • a random retry token
  • a generated Base64 session_id
  • the selected cipher
  • the negotiated congestion-control mode
  • the negotiated DATA protection mode
  • the server public key
• The client must answer with that exact same token and session metadata.
• Only after that token round-trip succeeds does the server create the session and begin sending DATA.
• After validation, the session is bound to the source IP:port that completed the challenge.
• session_id is still used as a session label, but it is not accepted from a different IP:port.

Retry Token

• USTP uses a plaintext retry-token step before any encrypted media session is accepted.
• Flow:
  • client sends HELLO
  • server replies with USTPS-CHALLENGE1 carrying token, session_id, selected cipher, negotiated congestion-control mode, negotiated DATA protection mode, and server public key
  • client echoes that token back in USTPS-CHALLENGE-REPLY1
  • only then does the server create the session and send USTPS-SESSION1
• Purpose:
  • prove that the sender at that source IP:port can actually receive packets there
  • avoid sending encrypted media immediately to an unvalidated source address
  • bind the final session creation to the endpoint that completed the round-trip
• The retry token is not the session key.
• It is only a reachability proof and handshake gate before the real USTP session is created.
• It is also not used as a nonce, not used as an ACK/NACK MAC key by itself, and not reused as packet payload state.

Historical protocol identifiers

• The project name is now USTP, but several on-wire ASCII identifiers still use the historical USTPS-* prefix.
• This is intentional for backward compatibility with existing implementations, captures, logs, and older deployments.
• In the current implementation, the following control identifiers remain on the wire:
  • USTPS-KEX1
  • USTPS-CHALLENGE1
  • USTPS-CHALLENGE-REPLY1
  • USTPS-SESSION1
  • USTPS-RESUME1
  • USTPS-RTT1
• The project/documentation name changed back to USTP, but those historical wire identifiers were not renamed in the protocol bytes.