VSHP Protocol Specification

VSHP is the VPN Share packet tunnel protocol. It carries IP packets from a paired client virtual interface to an Android gateway over USB, Wi-Fi, or hotspot-local transport.

Goals

Encrypted by default.
Transport independent.
Resumable after USB or Wi-Fi interruption.
Small enough for battery-conscious mobile operation.
Stable enough for third-party open-source clients.

Version

Current version: VSHP/1.

Frame Header

All multibyte integers are network byte order.

0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         magic "VSHP"                          |
+---------------+---------------+-------------------------------+
| version = 1   | frame_type    | flags                         |
+---------------+---------------+-------------------------------+
|                         stream_id                             |
+---------------------------------------------------------------+
|                         packet_number                         |
|                                                               |
+---------------------------------------------------------------+
|                         payload_length                        |
+---------------------------------------------------------------+
|                         payload...                            |
+---------------------------------------------------------------+

Header length: 24 bytes.

Frame Types

HELLO = 1: protocol version, platform, client public key, capabilities.
AUTH = 2: Noise handshake payload or resume ticket.
CONFIG = 3: virtual IP lease, DNS, MTU, routes, keepalive interval.
IP_PACKET = 4: encrypted IPv4/IPv6 packet from or to the client.
PING = 5: keepalive and counters.
RESUME = 6: session resumption request.
STATS = 7: byte, packet, loss, RTT, and battery hints.
CLOSE = 8: close code and human-readable reason.

Security Handshake

First pairing: Noise XXpsk2, X25519, ChaCha20-Poly1305, BLAKE2s/HKDF.
Known peer: Noise IKpsk2 with stored peer static key.
QR/USB pairing PSK is one-time and expires after 2 minutes.
Every encrypted frame binds protocol version, peer id, transport id, and transcript hash.
Replay window: 256 packet numbers per direction.
Rekey: after 1 GiB or 10 minutes, whichever comes first.

Pairing URI

vshare://pair?v=1&sid=<session>&server_pk=<base64url>&psk=<base64url>&transports=<csv>&expires=<unix>

Rules:

psk is 128 bits minimum.
sid is random and not reused.
expires is enforced by the phone and client.
QR pairing must be confirmed on the phone before a peer is trusted.

Client Configuration Payload

{
  "lease_id": "base64url",
  "peer_ipv4": "10.241.0.2/32",
  "peer_ipv6": "fd7a:7670:7368::2/128",
  "gateway_dns": "10.241.0.1",
  "routes": ["0.0.0.0/0", "::/0"],
  "mtu": 1280,
  "keepalive_ms": 15000,
  "idle_timeout_ms": 120000
}

IPv6 routes are omitted unless the gateway verifies upstream IPv6 through the active VPN.

Close Codes

0: normal close.
1: unsupported version.
2: authentication failed.
3: peer revoked.
4: VPN unavailable.
5: policy denied.
6: protocol error.
7: overload/backpressure.

MTU Policy

Default MTU is 1280.
USB may probe and raise the link MTU.
TCP MSS is clamped to mtu - 40 for IPv4 and mtu - 60 for IPv6.
Oversized packets are dropped with client-visible Packet Too Big signaling where possible.

3.6 KiB Raw Blame History