TrustTunnel/lib/README.md

AdGuard VPN endpoint

Building the library

Prerequisites

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

Building

Execute the following commands in 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. An HTTP/1.1 request has Upgrade header and its path starts with ReverseProxySettings.path_mask.
3. An HTTP/3 request has path starting with ReverseProxySettings.path_mask.

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 either HTTP1, or HTTP3.

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)
• authentication.radius.RadiusAuthenticator - delegates authentication to an authenticator communicating with it by the RADIUS protocol (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.

RADIUS authenticator

This authenticator implementation communicates with an authentication server by the Microsoft EAP CHAP Extensions Protocol, Version 2 over the Extensible Authentication Protocol over the RADIUS protocol.

Successful authentication procedure diagram:

sequenceDiagram
    participant Endpoint
    participant Authenticator

    Endpoint ->> Authenticator: RADIUS: code=AccessRequest[EAP: code=Response, type=Identity, user_name]
    Authenticator ->> Endpoint: RADIUS: code=AccessChallenge[EAP: code=Request, type=MsAuth[MS-CHAP-V2: code=Challenge]]
    Endpoint ->> Endpoint: MS-CHAP-V2::GenerateNTResponse()
    Endpoint ->> Authenticator: RADIUS: code=AccessRequest[EAP: code=Response, type=MsAuth[MS-CHAP-V2: code=Response]]
    Authenticator ->> Authenticator: Verify MS-CHAP-V2 response
    Authenticator ->> Authenticator: Authenticate
    Authenticator ->> Endpoint: RADIUS: code=AccessChallenge[EAP: code=Request, type=MsAuth[MS-CHAP-V2: code=SuccessRequest]]
    Endpoint ->> Endpoint: MS-CHAP-V2::CheckAuthenticatorResponse()
    Endpoint ->> Authenticator: RADIUS: code=AccessRequest[EAP: code=Response, type=MsAuth[MS-CHAP-V2: code=SuccessResponse]]
    Authenticator ->> Endpoint: RADIUS: code=AccessAccept[EAP: code=Success, type=MsAuth]

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

• SNI authentication:
  • user_name = sni@<id>@<hash[0..6]> - a special value which indicates the authentication way
    • <id> - the id of the current authentication session
    • <hash[0..6]> - the first 6 characters of the SNI
  • password = hash - corresponds to hash, as in SNI authentication
• Proxy authentication:
  • user_name and password correspond to token and credentials, as in Proxy authentication

The endpoint caches the authentication status and repeats the procedure for the client after the cache TTL (see RadiusAuthenticatorSettings.cache_ttl).

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