pasque 0.2.0

UDP and IP over HTTP/3
Documentation

Pasque

An UDP over HTTP/3 (RFC 9298) and IP over HTTP/3 implementation (RFC 9484). Built using Quiche as the HTTP/3 & QUIC implementation. The project is yet under construction, which probably is obvious when browsing the code, and some features are yet missing or not yet fully functional.

Building and testing

The code is built similarly to most Rust implementations. cargo build builds the binaries, cargo test runs a few tests on the implementation. There is an example client and server that demonstrate how the crate is used. Because the TUN interface used to implement the IP tunnel requires superuser privileges, the TUN-related tests are behind "tuntest" feature, so that the other functionality can be tested with normal user rights. To run full tests: sudo cargo test --features tuntest

psq-client.rs and psq-server.rs are simple examples on how to use the API. They open a UDP tunnel to server host port 9000, and optionally an IP tunnel forwarding traffic from the TUN interface to the HTTP/3 connection. Note that the latter requires sudo privileges, and is so far tested only on Linux.

Starting the example server:

cargo run --bin psq-server

The example server listens to UDP port 443 for incoming HTTP/3 and QUIC connections (use -a option to change the address and port to bind). Clients are allocated IP addresses from the given IP network, hence also the prefix length is given.

The server needs a JSON configuration file that gives links to files containing TLS certificate and private key are given in a JSON configuration file. The configuration file is given with -c option. By default, an example configuration file server-example.json is used, that contains link to an invalid certificate, but can be used for development and testing, if certificate validation is disabled at client.

Starting the example client:

cargo run --bin psq-client -- -i -d https://localhost

The example program will make a HTTP/3 CONNECT request to set up IP tunnel, in addition to UDP tunnel. For development and testing, if you are testing against a server with invalid certificate, use option --ignore-cert to disable certificate check.

Server configuration

An example server configuration file is provided in server-example.json. It demonstrates configurations for an IP tunnel endpoint (type: IpEndpoint), UDP proxy endpoint (type: UdpEndpoint) and an endpoint serving static files (type: Files).

IP Tunnel (IpEndpoint)

The following fields are used to configure an IP tunnel:

  • ifprefix: Prefix for the names of TUN interfaces created for clients. Each client is assigned a unique interface with this prefix (e.g., ifprefix-iN, where N is an integer).

  • addresspools: A list of network prefixes used to assign addresses to clients. Each new client receives one address from each specified prefix. This allows support for both IPv4 and IPv6 addresses.

  • routes: Network prefixes advertised to the client as available routes.

UDP Proxy (UdpEndpoint)

The UDP proxy currently has no configuration fields. All parameters are provided as URI variables in the HTTP request, as defined in RFC 9298.

Static File Sharing (Files)

The Files endpoint has a single field:

  • root: Path to the directory on the server’s file system from which static files are served.

Further information