How BibaVPN works

This chapter explains what BibaVPN does at a high level, how data moves, and how the main pieces fit together. For byte-level specifications, see PROTOCOL.md.

What problem it solves

Applications on your device normally open TCP or UDP connections to hosts on the internet. BibaVPN does not replace your IP stack. Instead it gives you a local proxy (SOCKS5 and optional HTTP CONNECT). Anything you point at that proxy is carried inside a single TLS connection that looks like a long-lived HTTPS WebSocket to a server you control. The server then opens the real connections to target hosts.

Design goals include making the outer traffic harder to classify with shallow DPI (fingerprints, framing, timing, padding—see your version’s flags in AGENTS.md). BibaVPN does not claim strong anonymity: the server operator can observe and modify proxied traffic the same way any egress proxy can.

End-to-end picture

┌─────────────┐   SOCKS5 or       ┌──────────────────┐   TLS + WebSocket   ┌──────────────────┐   TCP/UDP    ┌──────────┐
│ Applications│ ──HTTP CONNECT──► │ bibavpn-client   │ ───────────────────► │ bibavpn-server   │ ───────────► │ Internet │
│  (browser,  │   (cleartext,     │ (your computer)   │   one muxed tunnel  │ (your VPS/host)  │              │ targets  │
│   curl, …)  │    loopback)      └──────────────────┘                     └──────────────────┘              └──────────┘
└─────────────┘
  1. Client listens on 127.0.0.1 (or another address you choose) for SOCKS5 and optionally HTTP proxy.
  2. Each proxied flow becomes a logical stream inside the tunnel.
  3. Many streams are multiplexed over one to four WebSocket sessions for TCP (configurable), plus a separate WebSocket session for UDP mux. See PROTOCOL.md for details.
  4. Server terminates TLS, upgrades WebSocket, decrypts the inner layer, and dials the destination host/port your application requested.

Layer stack (conceptual)

From your application’s payload outward (typical TCP path):

  1. Application data — bytes the app would have sent on the wire.
  2. Inner framing — padded frames carrying stream payloads (length, optional padding).
  3. Biba v3 PSK layer — shared PSK, ChaCha20-Poly1305, opaque HELLO/ACK handshake, sealed control opcodes (AUTH, OPEN, mux helpers). Token is carried in the sealed AUTH path in current defaults—not in the WebSocket URL.
  4. WebSocket — binary frames (opcode 2) carrying ciphertext.
  5. TLS — encrypts the entire WebSocket bytestream (rustls by default; optional BoringSSL build on some platforms).
  6. TCP — to your server’s listen address.

A mermaid overview also exists in PROTOCOL.md — Stack at a glance.

Roles

Component Runs where Responsibility
bibavpn-client User device SOCKS5 / HTTP CONNECT front; TLS client; WebSocket client; Biba v3 crypto
bibavpn-server Your VPS or LAN host TLS server; HTTP/WebSocket accept; Biba v3 crypto; outbound TCP/UDP to targets
GUI apps (Android / desktop) User device Same core as client, packaged for end users; connect using invite or manual params

Credentials and names

For a working tunnel you normally configure:

  • token — server-issued shared secret used in the v3 AUTH path (not the same as putting a secret in the URL in the default mode).
  • psk — pre-shared key for the Biba v3 wire (HELLO/ACK and AEAD). Must match on client and server.
  • --proto-domain — string for domain-separated key derivation (default default on server; client must match, or match SNI behavior as documented in AGENTS.md).
  • TLS — client needs a hostname to verify (--sni) that matches the certificate (or use --pin-cert / CA trust). --insecure skips verification and is only for isolated labs.

Invite URIs (biba://…) bundle many of these parameters into one encrypted blob; the passphrase decrypts the blob. Share passphrase out of band from the URI. See PROTOCOL.md — Encrypted invite.

Camouflage HTTP

On the same TLS port, the server can answer ordinary HTTP GETs like a small static site or reverse proxy (--camouflage-dir, --camouflage-url) so casual probing sees plausible HTTP, while WebSocket upgrade to --ws-path (default /ws) carries the tunnel. Details: server flags in AGENTS.md.

Versioning and roadmap

Current release lines speak Biba v3 on the wire with optional BibaV1.2 shaping. A future BibaV4 inner protocol may introduce breaking changes. Until then, keep client, server, and app builds on the same version line. See README.md — v1.2.0 / BibaV4 and PROTOCOL.md — BibaV4.

Where to go next