Skip to content

Architecture

Jump to bottom
Next1971 edited this page Sep 6, 2026 · 1 revision

Architecture

MASQUE VPN is a self-hosted VPN system that carries IP traffic through MASQUE CONNECT-IP over HTTP/3 and QUIC. Clients authenticate to the server with mutual TLS (mTLS).

This page describes the high-level design. It is not a replacement for the versioned implementation and deployment documentation in the repository.

High-level view

A typical deployment has three main parts:

Client application
        |
        |  QUIC + HTTP/3 + mTLS
        |
MASQUE VPN server on your VPS
        |
        |  Routed IP traffic
        |
Internet / destination networks

The client creates a secure connection to the server. The server accepts the authenticated connection and carries IP packets between the client tunnel and the wider network.

The VPS is the network egress point seen by destination services. Its location, provider policy, IP reputation, firewall rules, routing, and network quality affect the practical behavior of a deployment.

Protocol stack

Layer Technology Role in MASQUE VPN
Transport QUIC Provides encrypted, multiplexed transport over UDP.
Application transport HTTP/3 Runs HTTP semantics over QUIC.
VPN tunnel MASQUE CONNECT-IP Carries IP traffic through an HTTP/3 tunnel.
Client authentication mTLS Lets both client and server authenticate with certificates.

The exact protocol behavior and implementation details can evolve with project releases. Refer to the repository and release notes for current compatibility information.

QUIC and HTTP/3

QUIC is a transport protocol designed to run over UDP. It provides encryption, connection management, and multiplexed streams without using TCP as the transport layer.

HTTP/3 uses QUIC as its transport. In MASQUE VPN, HTTP/3 provides the protocol context in which the client requests an IP tunnel.

Using QUIC means that UDP reachability matters. A server can be correctly configured while still being unreachable from a particular Wi-Fi network, mobile operator, enterprise network, or region if UDP traffic is filtered, blocked, rate-limited, or handled unusually.

MASQUE CONNECT-IP

MASQUE is a family of mechanisms for proxying network traffic over HTTP. CONNECT-IP is the MASQUE mechanism used to carry IP packets.

In practical terms, CONNECT-IP allows the client to send IP traffic through the authenticated HTTP/3 connection to the server. The server then routes that traffic according to its network configuration.

This differs from treating the project as a generic HTTP proxy: the tunnel is intended to carry IP-layer traffic, allowing the client VPN component to route selected or all device traffic through the server.

Mutual TLS

Mutual TLS, or mTLS, means that both sides of a connection use certificates:

  • The client verifies that it is talking to the intended server.
  • The server verifies that the connecting client holds an accepted client certificate and private key.

This is different from a deployment where only the server presents a certificate and clients authenticate only with a shared password.

mTLS provides strong client identity when credentials are handled correctly, but it also creates operational responsibilities:

  • Treat client private keys and credential files as secrets.
  • Never publish credentials in an issue, discussion, screenshot, backup, or repository commit.
  • Use separate client credentials where practical.
  • Revoke or replace credentials when a device is lost, replaced, or suspected to be compromised.
  • Protect backups that contain client or server key material.

See Security Model for trust boundaries and operational guidance.

Client applications

MASQUE VPN provides client applications for supported platforms, currently including Android, Android TV, and Windows.

Each client is responsible for integrating the tunnel with its operating system's VPN facilities and for managing the connection to the self-hosted server. Platform capabilities, permissions, routing behavior, and packaging can differ between clients.

For platform-specific status and setup details, use the versioned client documentation.

Server responsibilities

The server is operated by the person or organization deploying it. That owner is responsible for:

  • Selecting and maintaining the VPS or server host.
  • Allowing the required traffic through provider controls and firewalls.
  • Managing server certificates and client credentials.
  • Configuring routing, forwarding, and any required egress behavior.
  • Applying software and operating-system security updates.
  • Monitoring service health, capacity, and relevant logs.
  • Understanding local legal, provider, and network-policy constraints.

MASQUE VPN is not a hosted VPN service. The project does not provide public exit nodes or operate the VPS on the deployer's behalf.

Trust boundaries

The encrypted client-to-server connection protects tunnel traffic in transit between the client and the MASQUE VPN server. It does not remove every trust decision.

You still trust:

  • The server and the person or organization administering it.
  • The VPS provider and its infrastructure to the extent inherent in hosting.
  • The client device and its operating system.
  • The destination services you connect to.
  • DNS infrastructure and resolver configuration when DNS is not carried or configured as intended by your deployment.
  • The network path after traffic leaves the server toward its destination.

A VPN changes where traffic exits to the Internet; it does not automatically make a compromised device, insecure destination service, unsafe browser session, or poorly protected server secure.

Reachability and filtering

Network reachability is environment-specific. Successful operation depends on conditions such as VPS availability, firewall configuration, UDP treatment, DNS behavior, routing, local network policy, and regional filtering.

Review the repository's censorship resistance documentation for current project-specific guidance and limitations. Do not assume that a protocol alone guarantees operation on every restricted network.

Related pages

Clone this wiki locally