Repository navigation
Security Model
MASQUE VPN is an experimental, self-hosted VPN with private-CA authentication. It has not undergone an independent security audit.
This page describes trust boundaries and operational responsibilities, not a guarantee of anonymity, censorship resistance, or protection against every failure mode.
The deployment depends on:
- The client device and its operating system.
- The VPN client and its dependencies.
- The VPS operating system and server software.
- The operator who controls the VPS and certificate authority.
- The integrity of the software and credentials used during installation.
You control the server, but that does not eliminate trust in the VPS provider or the security of the host.
A private CA signs the server certificate and client certificates.
The client verifies the server using that CA and the configured server identity. The server verifies client credentials before granting VPN access.
Use a separate client identity for each device. This supports device-specific issuance and blocking and avoids simultaneous reuse of the same identity.
The QUIC tunnel requires a valid client certificate signed by the private CA. UDP does not serve a website.
In v2.1.0, the TCP TLS handshake requests a client certificate but does not require one merely to establish the connection.
VPN access still requires:
- A valid client certificate.
- An HTTP/2 CONNECT-IP request.
Browsers and connections without a valid client certificate receive an HTML page, not access to the tunnel.
Allowing a browser to reach that page does not make the VPN unauthenticated.
The server certificate remains signed by the private CA. A normal browser does not automatically trust it and shows a certificate warning.
The page is not a publicly trusted HTTPS deployment.
Do not disable VPN server verification to remove a browser warning. Keep:
insecure = falseEnabling insecure removes the client's authentication of the server and changes the security model.
The tunnel encrypts traffic between the client and VPS.
It does not make traffic beyond the VPS automatically end-to-end encrypted. Application protocols such as HTTPS provide their own end-to-end protection.
The VPS operator can observe traffic as it leaves the tunnel, subject to any application-level encryption.
In-tunnel DNS currently uses plaintext DNS rather than built-in DoH/DoT. It travels inside the encrypted client-to-VPS tunnel but is visible at the VPS.
A real profile.masque includes a client private key. Treat the complete profile and any equivalent QR code as credentials.
Never publish:
- CA, server, or client private keys.
- Real client profiles.
- Credential-bearing QR codes.
- Android signing keystores and passwords.
- Apple signing certificates with private keys, API keys, or provisioning secrets.
- SSH passwords or private keys.
Transfer profiles through secure channels and protect stored copies.
Back up ca.key securely. Losing it prevents issuing new certificates under the existing CA. Replacing the CA changes what existing clients must trust.
The server supports a CN denylist, including:
/opt/masque/blocked_cns
The process reads the file at startup. Applying a change requires a restart, which interrupts existing sessions.
This is not a certificate revocation list. It does not delete certificate files or revoke the CA itself.
Use the exact device CN and verify the result.
The optional application kill switch is off by default.
Its guarantees depend on the platform and process lifecycle:
- Android application-level blocking depends on the VPN service. OS-level Always-on VPN / Block connections without VPN is a separate mechanism.
- Windows application-level blocking depends on the MASQUE service and connection state. Stopping or killing the service is not a promise that blocking remains active.
- Do not infer identical behavior on iOS.
Test the actual failure cases you care about: network loss, reconnect, service termination, reboot, and manual disconnect.
Server deployment requires privileged operations: configuring services, forwarding, firewall rules, and credentials.
The experimental Windows VPS helper connects through SSH as root. Verify SSH host identity before trusting a new key.
install.sh is a fresh-install path and refuses to overwrite an existing CA, configuration, or service. Do not bypass that protection casually to perform an upgrade.
Docker deployment requires host networking, NET_ADMIN, and /dev/net/tun. Treat it as privileged networking software, not as a strong isolation boundary.
Check downloaded files against the matching release checksums and use available release-verification artifacts.
Checksums detect a mismatch against the expected digest; their assurance depends on obtaining the expected digest through a trusted channel.
CI builds and tests are not a third-party security audit. A release label does not guarantee that a binary suits every network or threat model.
The project does not promise:
- Anonymous access.
- A public VPN service.
- Multi-hop routing.
- Guaranteed filtering bypass.
- Indistinguishability from every ordinary HTTPS website.
- Permanent blocking after the VPN process is killed.
- Protection from a compromised client or VPS.
Follow the repository's security policy.
Do not include real credentials in a public issue. Use public issue tracking for non-sensitive bugs and sanitized diagnostic information.