vkturn

Documentation

Overview

DTLS-over-UDP listener that mirrors vk-turn-proxy server (see Moroka8/vk-turn-proxy PR #162). Binds a UDP socket, terminates DTLS (optionally wrapped in ChaCha20-XOR obfuscation), and forwards decrypted payload to a local UDP target — typically a kernel WireGuard instance.

The wire protocol is identical to the upstream Moroka8 server, so a goloom-wg-server using this package is a drop-in replacement for running vk-turn-server as a separate systemd unit. Same flags map to the same fields:

-listen  → relay.Config.ListenAddr
-connect → relay.Config.ConnectAddr
-wrap    → Options.UseWrap
-wrap-key → Options.WrapKey (hex-decoded, 32 bytes)
-debug   → Options.Debug

Not ported: -vless / -vless-bond. Those carry TCP for Xray/VLESS proxies, which is outside goloom's scope (WG = UDP).

Index

• func BuildAnton48Link(p LinkParams) (string, error)
• type LinkParams
• type LinkSettings
• type Options
  • func (Options) IsRelayOptions()
• type Transport
  • func (Transport) Kind() relay.Kind
  • func (Transport) Start(ctx context.Context, cfg relay.Config) (relay.Handle, error)

Functions

func BuildAnton48Link

func BuildAnton48Link(p LinkParams) (string, error)

BuildAnton48Link returns a `vkturnproxy://import?data=<base64>` URL ready to share. The base64 encoding is URL-safe-no-padding (anton48 parser accepts either variant).

Types

type LinkParams

type LinkParams struct {
	// Client-side WG identity from auto-provision.
	ClientPrivateKey string
	ServerPublicKey  string
	PresharedKey     string

	// Client WG interface address with CIDR mask (e.g. "10.66.1.2/24").
	TunnelAddress string

	// VK call URL (https://vk.com/call/join/<id>).
	VKLink string

	// Public vk-turn endpoint (e.g. "1.2.3.4:56001").
	PeerAddress string

	// WRAP layer toggle + key.
	UseWrap    bool
	WrapKeyHex string

	// Optional knobs (omitted from payload when zero).
	DNSServers     string
	NumConnections int

	// MTU for the client's WG interface. Zero → defaultMTU (1280).
	// Rationale: vk-turn double-encapsulates (WG inside DTLS inside
	// TURN ChannelData over UDP). Each layer adds overhead; on a 1500-
	// byte path MTU the client's WG MTU has to drop to ~1280 to avoid
	// IP fragmentation of the outer DTLS packets, which TURN relays
	// don't reassemble. The upstream Moroka8 quick_link.py hard-coded
	// 1280 for the same reason.
	MTU int

	// UseSrtp toggles the SRTP-framed transport on the iOS client side
	// (anton48 build125+). Server-side requires a vk-turn-srtp inbound
	// listening for DTLS-SRTP — set this true *only* when the link
	// targets a vkturnsrtp.Transport listener; leaving it false keeps
	// the legacy DTLS+WG path.
	UseSrtp bool
}

LinkParams gathers the inputs BuildAnton48Link needs. The caller (admin handler) collects these from inbound.Spec + provisioned allocation.

type LinkSettings

type LinkSettings struct {
	PrivateKey     string `json:"privateKey"`
	PeerPublicKey  string `json:"peerPublicKey"`
	PresharedKey   string `json:"presharedKey"`
	TunnelAddress  string `json:"tunnelAddress"` // e.g. "10.66.1.2/24"
	AllowedIPs     string `json:"allowedIPs"`    // e.g. "0.0.0.0/0"
	VKLink         string `json:"vkLink"`        // "https://vk.com/call/join/<id>"
	PeerAddress    string `json:"peerAddress"`   // "1.2.3.4:56001" — the vk-turn listener
	UseDTLS        bool   `json:"useDTLS"`
	UseWrap        bool   `json:"useWrap"`
	WrapKeyHex     string `json:"wrapKeyHex"`        // 64 hex chars; 64 zeroes when UseWrap=false (anton48 validator)
	UseSrtp        bool   `json:"useSrtp,omitempty"` // anton48 v1.0-build125+: enables SRTP-framed transport
	DNSServers     string `json:"dnsServers,omitempty"`
	NumConnections int    `json:"numConnections,omitempty"`
	MTU            int    `json:"mtu,omitempty"` // see defaultMTU
}

LinkSettings is the JSON payload anton48's BackupManager.importLink decodes. Field names match anton48 *exactly* — don't rename.

type Options

type Options struct {
	// UseWrap enables the ChaCha20-XOR obfuscation layer between UDP
	// and DTLS — symmetric to client `-wrap`. When true, [WrapKey]
	// must be exactly 32 bytes; the client side must use the same key.
	UseWrap bool

	// WrapKey — 32-byte shared secret consumed when UseWrap is true.
	// Ignored otherwise.
	WrapKey []byte

	// Debug enables per-session throughput logging every 5s. Off by
	// default; turn on only when investigating throughput issues —
	// it adds one goroutine per active session.
	Debug bool
}

Options is the vkturn-specific knob set passed via relay.Config.Options.

Zero value (`Options{}`) is valid: DTLS+UDP, no WRAP obfuscation, no throughput logging — the defaults that match vk-turn-proxy's `vk-turn-server -listen … -connect …` invocation without flags.

func (Options) IsRelayOptions

func (Options) IsRelayOptions()

IsRelayOptions tags Options as a member of relay.Options.

type Transport

type Transport struct{}

Transport is the relay.Relay implementation for KindVKTurn. Stateless singleton — one instance lives in the registry, each call to Start spawns an independent [listener].

func (Transport) Kind

func (Transport) Kind() relay.Kind

Kind reports the relay kind this Transport handles.

func (Transport) Start

func (Transport) Start(ctx context.Context, cfg relay.Config) (relay.Handle, error)

Start binds the listener and returns a Handle. See relay.Relay.Start contract — ctx is only honoured during setup; lifecycle past return is controlled by Handle.Close.