Post-quantum QUIC-based VPN
Quincy is a VPN client and server implementation using the QUIC protocol with support for pre-quantum, hybrid and post-quantum cryptography.
Binaries and installers are available for:
Using cargo, installation of any published version can be done with a simple command:
# CLI client binary
cargo install --locked quincy-client
# CLI server binary
cargo install --locked quincy-server
# Identity management utility
cargo install --locked quincy-identity
# Client GUI binaries
cargo install --locked quincy-guiDocker images are available on GitHub Container Registry with tags for the latest, major, minor, and specific versions:
ghcr.io/quincy-rs/quincy:latest: The latest version of Quincyghcr.io/quincy-rs/quincy:2: The latest 2.x releaseghcr.io/quincy-rs/quincy:2.2: The latest 2.2.x releaseghcr.io/quincy-rs/quincy:2.2.0: A specific releaseNote: it is not possible to use the dns_servers configuration option due to how Docker networking works
To run the client/server, you need to add a volume with the configuration files and add needed capabilities:
docker run
--rm # remove the container after it stops
--cap-add=NET_ADMIN # needed for creating the TUN interface
--device=/dev/net/tun # needed for creating the TUN interface
-p "55555:55555" # server port-forwarding
-v :/etc/quincy # directory with the configuration files
ghcr.io/quincy-rs/quincy:latest # or any of the other tags
quincy-server --config-path /etc/quincy/server.tomlPlatform-specific installers for the GUI client are available for download from the GitHub releases:
.exe).dmg).deb) and AppImage (.AppImage)Note for macOS users: After installing, you may need to remove the quarantine attribute before the app can be launched:
xattr -d com.apple.quarantine /Applications/Quincy.appAs Quincy does not rely upon any non-Rust libraries, the build process is incredibly simple:
cargo buildIf you additionally want to build Quincy in release mode with optimizations, add the --release switch:
cargo build --releaseThe resulting binaries can be found in the target/debug and target/release directories.
A C compiler (Clang or GCC) is required for building due to depending on the aws-lc-rs cryptography module.
For more information, see aws-lc-rs build instructions.
jemalloc: Uses the jemalloc memory allocator on UNIX systems for improved performance [default: enabled]offload: Enables GSO/GRO offload optimization for TUN interfaces on Linux [default: enabled]metrics: Enables the Prometheus metrics endpoint on the server (see Metrics) [default: disabled]Quincy provides a couple of binaries based on their intended use:
quincy-client: The VPN client CLIquincy-server: The VPN server CLIquincy-identity: A utility for generating keys and certificates for both TLS and Noise modesquincy-client-gui: The VPN client GUIquincy-client-daemon: The VPN client daemon (background privileged service)The Quincy client requires a separate configuration file, an example of which can be found in examples/client.toml.
The documentation for the client configuration file fields can be found here.
With the configuration file in place, the client can be started using the following command:
quincy-client --config-path examples/client.tomlRoutes are set by default to the address and netmask received from the server. Any additional routes now have to be set up manually.
The Quincy client GUI is cross-platform and built using iced. It provides a simple interface for managing and (dis)connecting multiple client instances and viewing connection statistics.
All configuration files are stored either in ~/.config/quincy (Linux, macOS) or %APPDATA%\quincy (Windows).
The GUI runs in unprivileged mode and uses a separate executable (quincy-client-daemon) to handle privileged operations such as creating the TUN interface and setting up routes.
The current way this is done is using rather primitive privilege escallation commands, which do not have the best user experience. This is subject to change and will be improved upon in the future.
The Quincy server requires a separate configuration file, an example of which can be found in examples/server.toml.
The documentation for the server configuration file fields can be found here.
With the configuration file in place, the client can be started using the following command:
quincy-server --config-path examples/server.tomlPlease keep in mind that the pre-generated certificate in examples/cert/server_cert.pem
is self-signed and uses the hostname quincy. It should be replaced with a proper certificate,
which can be generated using the instructions in the Certificate management section.
Quincy authenticates clients at the QUIC handshake layer using public keys (Noise) or certificate fingerprints (TLS). There are no passwords involved.
Users are managed through a TOML file referenced by the users_file field in the server configuration (example can be found in examples/users.toml):
[users.alice]
# Base64-encoded Noise public keys authorized for this user
authorized_keys = [
"base64-encoded-x25519-public-key",
]
# TLS certificate fingerprints authorized for this user
authorized_certs = [
"sha256:2dba01529210e4e828265d56329df1b85a8f9aedccdd3fef67ab502b57cb0029",
]
[users.bob]
authorized_keys = []
authorized_certs = [
"sha256:abc123...",
]Each user can have any number of authorized Noise public keys and TLS certificate fingerprints. The server identifies the connecting client by matching their handshake identity against these entries.
To generate the values for this file, use the quincy-identity utility:
# Derive a Noise public key from a private key
quincy-identity noise genkey | quincy-identity noise pubkey
# Get the fingerprint of a TLS client certificate
quincy-identity tls fingerprint --cert client_cert.pemQuincy uses the QUIC protocol implemented by quinn to create an encrypted tunnel between clients and the server.
Client authentication is performed during the QUIC handshake itself, either through mutual TLS (certificate fingerprint verification) or through the Noise IK handshake (static public key verification). No additional authentication protocol is needed after the handshake.
Once the handshake completes, the server identifies the client, allocates a tunnel IP from its address pool and sends it to the client over a uni-directional QUIC stream. The client then creates a TUN interface with the assigned address.
With the tunnel set up, data transfer happens through unreliable QUIC datagrams (lower latency and overhead). A connection task is spawned for each client, relaying packets between the TUN interface and the QUIC connection.
The tokio runtime is used to provide an efficient and scalable implementation.
Quincy supports two cryptographic protocol modes for the QUIC tunnel: TLS and Noise. The mode is selected in the [protocol] section of both the server and client configuration files.
TLS 1.3 is the default protocol mode. It uses mutual TLS (mTLS) for both server and client authentication, with support for three key exchange algorithms:
Standard: ECDH (X25519)Hybrid: X25519 + ML-KEM-768PostQuantum: ML-KEM-768TLS mode requires a certificate and private key on both the server and the client. The server verifies client identity by matching the client certificate's SHA-256 fingerprint against the entries in the users file. See Certificate management for details on generating and configuring certificates.
Certificates and keys can be loaded from files or supplied as PEM strings directly in the config. TOML multi-line basic strings ("""...""") are a good fit for PEM data when you want the config to show the certificate on multiple lines.
Server
[protocol]
mode = "tls"
key_exchange = "hybrid"
certificate_file = "server_cert.pem"
certificate_key_file = "server_key.pem"
# Or use inline PEM strings:
# certificate = """
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# """
# certificate_key = """
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
# """Client
[protocol]
mode = "tls"
key_exchange = "hybrid"
trusted_certificate_paths = ["server_cert.pem"]
# Or trust inline PEM strings:
# trusted_certificates = [
# """
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# """
# ]
client_certificate_file = "client_cert.pem"
client_certificate_key_file = "client_key.pem"
# Or use inline PEM strings:
# client_certificate = """
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# """
# client_certificate_key = """
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
# """Noise mode uses the Noise IK handshake pattern instead of TLS. Both the server and the client have static keypairs, and both sides know the other's public key before the handshake begins. This has two main advantages:
The server identifies connecting clients by matching their public key against the entries in the users file. Three key exchange algorithms are supported:
| Mode | Key exchange | Private key | Public key |
|---|---|---|---|
Standard |
X25519 | 32 bytes | 32 bytes |
Hybrid |
X25519 + ML-KEM-768 | 128 bytes | 1216 bytes |
PostQuantum |
ML-KEM-768 | 96 bytes | 1184 bytes |
Using quincy-identity, you can generate keypairs for both the server and the client:
…Both the server and each client need their own keypair. Place the keys in the respective configuration files:
Server
[protocolNo open issues yet, or sync has not completed.