TrustTunnel/lib

TrustTunnel endpoint

Building the library

Prerequisites

• Rust 1.85 or higher: use a preferred way from https://www.rust-lang.org/tools/install
• libclang 9.0 or higher

Building

Execute the following commands in the Terminal:

cargo build

to build the debug version, or

cargo build --release

to build the release version.

Features description

Traffic forwarding

As for now, the endpoint can demultiplex client's connections multiplexed in either HTTP/1, or HTTP/2, or HTTP/3 session. An application can set up how the endpoint forwards the demultiplexed client's connection by setting Settings.forward_protocol. The available options (see settings.ForwardProtocolSettings) are:

• routing a connection directly to its target host
• routing a connection though a SOCKS5 proxy

ICMP forwarding

As an optional feature, the endpoint can also forward ICMP packets from a client. This feature can be set up by setting Settings.icmp. An application MUST set up an interface name to bind the ICMP socket to, and MAY tweak some other settings, like the timeouts and message queue size.

Reverse proxy

Client's connection is treated as a reverse proxy stream in the following cases:

1. A TLS session or QUIC connection has the SNI set to the host name equal to one from TlsHostsSettings.reverse_proxy.
2. If a request path starts with ReverseProxySettings.path_mask, it is routed to reverse proxy.
3. Otherwise, routing is defined by ping_path and speedtest_path configuration. Requests that do not match ping, speedtest, or reverse proxy rules are treated as tunnel requests.

The stream is used for mutual client and endpoint notifications and some control messages. The endpoint does TLS termination on such connections and translates HTTP/x traffic into HTTP/1.1 protocol towards the server and back into original HTTP/x towards the client. Like this:

(client) TLS(HTTP/x) <--(endpoint)--> (server) HTTP/1.1

The translated HTTP/1.1 requests have the custom header X-Original-Protocol appended. For now, its value can be HTTP1, HTTP2, or HTTP3.

Note: HTTP/3 reverse proxy handling keeps the write side open when the client finishes sending the request body, to avoid truncating large responses.

Authentication

Client authentication options

SNI authentication

A client connects to the endpoint with SNI set to hash.domain_name, where:

• hash - md5(application_id + ':' + token + ':' + credentials)
• domain_name - the endpoint's original domain name (e.g. myvpn.org)

Proxy authentication

A client connects to the endpoint using the proxy HTTP authentication mechanism with the "basic" scheme: Proxy-Authorization: Basic base64(token + ':' + credentials).

Endpoint authentication methods

An application can set up the authentication method being used by the endpoint by setting Settings.authenticator. The application can provide its own authenticator implementation (see the authentication.Authenticator trait), or use one of the implementations provided by the library:

• authentication.DummyAuthenticator - authenticates any request
• authentication.file_based.FileBasedAuthenticator - authenticates a request basing on the file containing credentials (see here)
• SOCKS5 authentication - delegates authentication to the SOCKS5 forwarder (see here)

Please note, that the first 2 are very simple authenticator implementations which are intended mostly for testing purposes and do not respect network security practices.

File based authenticator

The file must contain an application id (applicationId: <string>), token (token: <string>), and credentials (credentials: <string>). Each one must be on a new line. The order does not matter.

SOCKS5 authenticator

Standard authentication

In case Socks5ForwarderSettings.extended_auth is set to false, the endpoint performs the standard authentication procedure according to the RFC 1929.

Depending on the client-side authentication way, the username and password are as follows:

• SNI authentication:

  • both username and password = hash - corresponds to hash, as in SNI authentication

• Proxy authentication:

  • username corresponds to token, as in Proxy authentication
  • password corresponds to credentials, as in Proxy authentication

Extended authentication

The extended authentication uses 0x80 as an authentication method. After a server selects this authentication method, a client sends an authentication request in the following format:

+-----+-----------+-----+--------+
| VER |   EXT(0)  |     | EXT(n) |
+-----+-----------+ ... +--------+
|  1  | see below |     |        |
+-----+-----------+-----+--------+

Where:

• VER - the current extended authentication version: 0x01

• EXT[i] - an extension in the following format:

  +------+--------+----------+
  | TYPE | LENGTH |   VALUE  |
  +------+--------+----------+
  |  1   |    2   | Variable |
  +------+--------+----------+
  

  Where:

  • TYPE - a type of the extension value (see [ExtendedAuthenticationValue])
  • LENGTH - the length of the extension value
  • VALUE - the extension value

Available extensions:

• TERM: type = 0x00, length = 0 - terminating extension, marks a message end
• DOMAIN: type = 0x01, length = (0..MAX], value = UTF-8 string - hostname which a client used for the TLS session (SNI)
• CLIENT_ADDRESS: type = 0x02, length = [4|16], value = Bytes - public IP address of the VPN client
• USER_AGENT: type = 0x03, length = (0..MAX], value = UTF-8 string - user agent of the VPN client
• PROXY_AUTH: type = 0x04, length = (0..MAX], value = base64 string - <credentials> part of the Proxy-Authorization header
• SNI_AUTH: type = 0x05, length = 0 - marks that the VPN client tries to authenticate using SNI

A message MUST end with the TERM extension.

The server responds with a standard message as in the RFC.

Metrics collecting

In order to collect some metrics of a running endpoint, an application can set up it to listen for the metrics collecting requests (see Settings.metrics). An endpoint running with this feature will listen on the configured address (MetricsSettings.address) for plain HTTP/1 requests. The following paths are available:

• /health-check - used for pinging the endpoint, so it will respond with 200 OK
• /metrics - used for metrics collecting, so it will respond with a bunch of values according to the prometheus specification

License

Apache 2.0