net.vmess

VMess is the older protocol of the V2Ray family, and unlike VLESS it encrypts for itself. The client proves it holds a user's UUID with an authentication id that contains the current time, sends the request (the target address and the session keys) encrypted under keys derived from the UUID, and then sends the payload in encrypted chunks. The server answers with its own encrypted header and its own chunks. Anyone watching sees random bytes, whatever carries them.

This package implements only the AEAD form, the one used since V2Ray 4.28 and the only one current clients still produce: the user is identified by the encrypted authentication id and the header is sealed with AES-128-GCM. The older MD5 based form, the one that needs alterId to be above 0, is not implemented. Set alterId to 0 on both sides (it is the default in current clients).

The package is both halves. Dial connects a client through net.transport and sends the header, Accept reads it on a server, Read and Write move the payload and ReadPacket reads one chunk as a UDP datagram. AsStream, DialOver and AcceptOver connect it to net.tunnel streams. The lower level functions (key derivation, the sealed header, the chunk encoder) are public, because the protocol is easiest to understand, and to test, one piece at a time.

The body encryptions

The header is always sealed with AES-128-GCM under keys derived from the UUID, whichever body type is chosen. The options in Request.option are bits: OptChunkStream frames the body in chunks, OptChunkMask hides the chunk lengths with a SHAKE-128 stream, OptPadding adds random padding to each chunk, OptAuthLength authenticates the lengths with the body cipher. Dial uses DefaultOption for the security type; to choose the bits yourself, call Client on a connection you opened.

What trips people up

• The two clocks must agree. The authentication id contains the time and a server accepts only ids within TimeWindow seconds, 120, of its own clock. A phone or a server with a wrong clock gets unknown user or stale timestamp and nothing else. This is the first thing to check when a correct UUID is refused.
• Share one replay filter. Accept remembers the authentication ids it has seen and refuses a repeat. Make one with NewReplayFilter and pass the same one to every Accept call of a server; it is safe to use from several threads. Once it holds more than 4096 ids it drops the ones older than four minutes.
• A refused client is not told. Dial only sends the header. A wrong UUID, a stale clock or a replayed id makes the server close the connection, and the client sees that as a failed read.
• The server must support the security type. An Accept that reads a type other than the four above fails with unsupported security type.
• There are no vmess:// links. The base64 JSON share format of V2RayN and others is not parsed here. Take the fields from it yourself.
• Close frees the keys. Call Close once on each side when you are done.

The building blocks

This program derives a user's command key from a UUID, makes an authentication id for a given time, opens it again (which also gives back the time), shows that another user's key cannot open it, and seals a small header. The numbers that come out are fixed, so they can be compared with another implementation.

import net.transport
import net.vmess

const ID := "b831381d-6324-4d53-ad4f-8cda48b30811"

func main:
    key := vmess.CmdKey(transport.ParseUUID(ID))
    println "command key", transport.ToHex(key)

    stamp := 1700000000 as i64
    salt := transport.FromHex("a1b2c3d4")
    authid := vmess.CreateAuthID(key, stamp, salt)
    println "auth id", transport.ToHex(authid)

    mut when := 0 as i64
    println "opens with the right key:", vmess.OpenAuthID(key, authid, when), when == stamp
    other := vmess.CmdKey(transport.ParseUUID("5783a3e7-e373-51cd-8642-c83782b807c5"))
    println "refused for another user:", not vmess.OpenAuthID(other, authid, when)

    nonce := transport.FromHex("1112131415161718")
    sealed := vmess.SealHeader(key, transport.FromStr("a small header"), stamp, salt, nonce)
    println "sealed header is", sealed.len, "bytes"
    println "time window in seconds:", vmess.TimeWindow
    println "default option for aes-gcm:", vmess.DefaultOption(vmess.SecAES128GCM)
    println "default option for none:", vmess.DefaultOption(vmess.SecNone)
    println "default option for zero:", vmess.DefaultOption(vmess.SecZero)
end

Quick start: a client and a server over TCP

The server listens with transport.Listen, accepts with transport.Accept and hands each connection to vmess.Accept with its list of users and the shared replay filter. The client dials with vmess.Dial and picks the body encryption. The target in the header is what a real server would connect onward to; this echo server just reports it.

import mem
import str
import sync
import net.transport
import net.vmess

const ID := "b831381d-6324-4d53-ad4f-8cda48b30811"

mut port := 0
mut ready := sync.NewWaitGroup()
mut seen := ""

func server():
    l := transport.Listen(0, transport.Settings {})
    port = transport.ListenerPort(l)
    sync.Done(ready)
    mut users := Vector {} as Vector<vmess.User>
    users.push(vmess.NewUser(ID))
    mut rf := vmess.NewReplayFilter()
    buf := mem.Allocate(4096 as u64)
    repeat 3:
        mut c := vmess.Accept(transport.Accept(l), users, rf)
        if not c.ok:
            seen += "refused(" + c.err + ") "
            continue
        end
        seen += c.req.addr.host + " security " + str.FromInt(c.req.security as i64) + "; "
        n := vmess.Read(c, buf, 4096)
        vmess.Write(c, buf, n)
        vmess.Close(c)
    end
    mem.Free(buf)
    transport.CloseListener(l)
end

func talk(security: int):
    target := transport.NewAddr("example.com", 443)
    mut c := vmess.Dial("127.0.0.1", port, transport.Settings {}, ID, security, vmess.CmdTCP, target)
    mut msg := transport.FromStr("hello through vmess")
    vmess.Write(c, msg.p, msg.len)
    buf := mem.Allocate(4096 as u64)
    n := vmess.Read(c, buf, 4096)
    println security, (buf as str).substr(0, n)
    mem.Free(buf)
    transport.FreeBytes(msg)
    vmess.Close(c)
end

func main:
    sync.Add(ready, 1 as i64)
    t := spawn(server)
    sync.Wait(ready)
    talk(vmess.SecAES128GCM)
    talk(vmess.SecChaCha20Poly1305)
    talk(vmess.SecNone)
    join(t)
    println seen
end

A user the server does not know

The client cannot tell by itself. The server finds no matching key, says unknown user or stale timestamp, and closes the connection. A real server should do nothing else: sending an error would tell a scanner that it found a proxy.

import sync
import net.transport
import net.vmess

const GOOD := "b831381d-6324-4d53-ad4f-8cda48b30811"
const OTHER := "5783a3e7-e373-51cd-8642-c83782b807c5"

mut port := 0
mut ready := sync.NewWaitGroup()
mut verdict := ""

func server():
    l := transport.Listen(0, transport.Settings {})
    port = transport.ListenerPort(l)
    sync.Done(ready)
    mut users := Vector {} as Vector<vmess.User>
    users.push(vmess.NewUser(GOOD))
    mut rf := vmess.NewReplayFilter()
    mut c := vmess.Accept(transport.Accept(l), users, rf)
    verdict = c.ok ? "accepted " + c.user : "refused: " + c.err
    vmess.Close(c)
    transport.CloseListener(l)
end

func main:
    sync.Add(ready, 1 as i64)
    t := spawn(server)
    sync.Wait(ready)
    mut c := vmess.Dial("127.0.0.1", port, transport.Settings {}, OTHER, vmess.SecAES128GCM, vmess.CmdTCP, transport.NewAddr("example.com", 80))
    join(t)
    println verdict
    vmess.Close(c)
end

VLESS carrying VMess

A stream wrapper turns any protocol into the carrier of another. Here an outer VLESS connection runs over an in-memory pipe and an inner VMess connection runs inside it, with different users and different targets. On a real network the outer one would be VLESS over WebSocket and TLS and the inner one VMess, which encrypts the payload end to end even when a CDN terminates the outer TLS.

import mem
import sync
import net.transport
import net.tunnel
import net.vless
import net.vmess

const OUTER := "b831381d-6324-4d53-ad4f-8cda48b30811"
const INNER := "5783a3e7-e373-51cd-8642-c83782b807c5"

mut pipe := tunnel.NewPipe()
mut done := sync.NewWaitGroup()
mut seen := ""

func server():
    mut vl := Vector {} as Vector<vless.User>
    vl.push(vless.NewUser(OUTER, ""))
    mut vm := Vector {} as Vector<vmess.User>
    vm.push(vmess.NewUser(INNER))
    mut rf := vmess.NewReplayFilter()
    outer := vless.AcceptOver(tunnel.PipeB(pipe), vl)
    inner := vmess.AcceptOver(vless.AsStream(outer), vm, rf)
    seen = outer.req.addr.host + " then " + inner.req.addr.host
    s := vmess.AsStream(inner)
    buf := mem.Allocate(256 as u64)
    n := s.ReadBytes(buf, 256)
    s.WriteBytes(buf, n)
    mem.Free(buf)
    s.Close()
    sync.Done(done)
end

func main:
    sync.Add(done, 1 as i64)
    _t := spawn(server)
    outer := vless.DialOver(tunnel.PipeA(pipe), OUTER, "", vless.CmdTCP, transport.NewAddr("hop.example", 443))
    inner := vmess.DialOver(vless.AsStream(outer), INNER, vmess.SecChaCha20Poly1305, vmess.CmdTCP, transport.NewAddr("final.example", 443))
    s := vmess.AsStream(inner)
    s.Write("two layers deep")
    buf := mem.AllocateZeroed(256 as u64)
    n := s.ReadBytes(buf, 256)
    println (buf as str).substr(0, n)
    mem.Free(buf)
    s.Close()
    sync.Wait(done)
    println "server saw", seen
end

VMess over WebSocket and TLS behind a CDN

Do the CDN steps from the net.transport page: a proxied domain, a secret WebSocket path, TLS to the CDN with the front name as sni, your domain as host. VMess does the encryption, so it also protects the payload from the CDN.

import net.transport
import net.vmess

func main:
    mut s := transport.Settings {}
    s.network = "ws"
    s.tls = true
    s.sni = "front.example.net"
    s.host = "vpn.example.org"
    s.path = "/vm-31c9"
    s.alpn = "http/1.1"

    target := transport.NewAddr("example.com", 80)
    mut c := vmess.Dial("front.example.net", 443, s, "b831381d-6324-4d53-ad4f-8cda48b30811", vmess.SecAES128GCM, vmess.CmdTCP, target)
    if not c.ok:
        println "could not connect:", c.err
        ret
    end
    mut req := transport.FromStr("HEAD / HTTP/1.0\r\nHost: example.com\r\n\r\n")
    vmess.Write(c, req.p, req.len)
    transport.FreeBytes(req)
    vmess.Close(c)
end

On the server, listen with network = "ws", the same path and host and with tls off when the CDN or your reverse proxy terminates TLS. For each connection, in a worker thread, call transport.AcceptRaw, transport.Upgrade and then vmess.Accept. Keep the server's clock right (the time window is 120 seconds), and tell your users to do the same.

Share links

Apps share a VMess server as vmess:// followed by base64 of a JSON object (the v2rayN form, the same one tunnel.ParseLink reads). ParseLink reads it into a Link: check ok and read err when it is false. FormatLink writes one back, LinkSettings turns it into the net.transport settings (WebSocket path and ?ed= early data, gRPC service name, TLS name) and DialLink dials it. SecurityByName and SecurityName convert between names such as chacha20-poly1305 and the security numbers; auto means AES-128-GCM. The legacy aid is parsed and kept but only 0 is meaningful.

Limits

• AEAD only. There is no legacy (alterId above 0) mode, and no compatibility with servers or clients that need it.
• The authenticated length option follows Xray. OptAuthLength derives its length key and nonce from the request key and IV in both directions, seals the length with AES-128-GCM (also for ChaCha20-Poly1305 bodies) and was checked against Xray and sing-box in the interop run (see docs/VPN_INTEROP.md for the matrix). Dial never sets it; choose the bits with Client.
• Interoperability was tested separately. The header, the authentication id, the key derivation and the chunk formats are checked in this repository against fixed byte vectors and the two halves of this package against each other (over TCP, TLS, WebSocket and a pipe). The interop harness runs the package against real Xray and sing-box builds; its results are in docs/VPN_INTEROP.md.
• Multiplexing is Mux.Cool. Dial with CmdMux and call MuxClient; on the server, when the accepted request has CmdMux, call MuxServer. Sessions come from net.transport (MuxOpen, MuxAccept).
• Weak primitives by design. VMess uses MD5 for the command key and AES in ECB mode for one block of the authentication id; these are the protocol's, not choices of this package. The payload ciphers are authenticated (AES-GCM, ChaCha20-Poly1305).
• SecNone and SecZero do not encrypt the payload. Use them only inside TLS you trust.
• Replay protection is per process. The filter lives in memory, so a restart forgets it, but the time window still limits what can be replayed.

Types

struct User

struct ReplayFilter

struct Conn

struct Link

struct Request

Constants and variables

const TimeWindow: i32 = 120

Functions

func AsStream(c: Conn): dyn tunnel.Stream

func DialOver(s: dyn tunnel.Stream, uuid: str, security: int, command: int, target: transport.Addr): Conn

func AcceptOver(s: dyn tunnel.Stream, users: Vector<User>, rf &: ReplayFilter): Conn

func MuxClient(c: Conn): transport.Mux

func MuxServer(c: Conn): transport.Mux

func NewUser(uuid: str): User

func NewReplayFilter(): ReplayFilter

func DefaultOption(security: int): int

func Client(t: transport.Conn, uuid: str, security: int, option: int, command: int, addr: transport.Addr): Conn

func Dial(host: str, port: int, s: transport.Settings, uuid: str, security: int, command: int, target: transport.Addr): Conn

func Accept(t: transport.Conn, users: Vector<User>, rf &: ReplayFilter): Conn

func Read(c &: Conn, buf: void*, max: int): int

func ReadPacket(c &: Conn, out &: transport.Bytes): bool

func Write(c &: Conn, p: void*, n: int): bool

func Close(c &: Conn)

func EncodeChunks(security: int, option: int, key: transport.Bytes, iv: transport.Bytes, parts: Vector<transport.Bytes>, with_end: bool): transport.Bytes

func SecurityByName(name: str): int

func SecurityName(sec: int): str

func ParseLink(link: str): Link

func FormatLink(l: Link): str

func LinkSettings(l: Link): transport.Settings

func DialLink(l: Link, command: int, target: transport.Addr): Conn

func KDF(key: transport.Bytes, label: str, a: transport.Bytes, b: transport.Bytes): transport.Bytes

func KDF16(key: transport.Bytes, label: str, a: transport.Bytes, b: transport.Bytes): transport.Bytes

func KDF12(key: transport.Bytes, label: str, a: transport.Bytes, b: transport.Bytes): transport.Bytes

func CmdKey(uuid: transport.Bytes): transport.Bytes

func Sha256(data: transport.Bytes): transport.Bytes

func AES128Block(key: transport.Bytes, block: transport.Bytes, decrypt: bool): transport.Bytes

func Shake128(msg: transport.Bytes, outlen: int): transport.Bytes

func CRC32(data: transport.Bytes): i64

func FNV1a(data: transport.Bytes): i64

func CreateAuthID(cmd_key: transport.Bytes, ts: i64, rand4: transport.Bytes): transport.Bytes

func OpenAuthID(cmd_key: transport.Bytes, authid: transport.Bytes, ts &: i64): bool

func SealHeader(cmd_key: transport.Bytes, data: transport.Bytes, ts: i64, rand4: transport.Bytes, nonce: transport.Bytes): transport.Bytes

func SealHeaderNow(cmd_key: transport.Bytes, data: transport.Bytes): transport.Bytes

func OpenHeaderLength(cmd_key: transport.Bytes, authid: transport.Bytes, enc_len: transport.Bytes, nonce: transport.Bytes): int

func OpenHeader(cmd_key: transport.Bytes, authid: transport.Bytes, enc: transport.Bytes, nonce: transport.Bytes): transport.Bytes

func SealResponseHeader(resp_key: transport.Bytes, resp_iv: transport.Bytes, header: transport.Bytes): transport.Bytes

func OpenResponseLength(resp_key: transport.Bytes, resp_iv: transport.Bytes, enc_len: transport.Bytes): int

func OpenResponseHeader(resp_key: transport.Bytes, resp_iv: transport.Bytes, enc: transport.Bytes): transport.Bytes

func EncodeRequest(r: Request): transport.Bytes

func DecodeRequest(b: transport.Bytes, r &: Request): bool