Proxy Protocols (SOCKS5 & HTTP)
Relevant source files
The following files were used as context for generating this wiki page:
HXLibs provides a structured framework for implementing and utilizing network proxies within asynchronous C++ applications. The system supports SOCKS5 and HTTP proxy protocols, enabling HttpClient and HttpsClient to route traffic through intermediary servers for security, anonymity, or network traversal.
Core Architecture
The proxy system utilizes the Curiously Recurring Template Pattern (CRTP) to define a common interface for different proxy implementations.
Proxy Base Class
The Proxy<T> class serves as the base for all proxy types. It maintains a reference to a HttpIO object to perform network operations and requires derived classes to implement a connect method.
The diagram shows the class hierarchy where specific proxy protocols inherit from the CRTP Proxy base.
Sources: include/HXLibs/net/protocol/proxy/Proxy.hpp:33-47, include/HXLibs/net/protocol/proxy/Socks5Proxy.hpp:34-39, include/HXLibs/net/protocol/proxy/HttpProxy.hpp:34-39
SOCKS5 Proxy Implementation
The Socks5Proxy class implements the SOCKS Protocol Version 5. It handles authentication, method negotiation, and connection requests.
Connection Workflow
- Handshake: Negotiates the authentication method with the server.
- Sub-negotiation: Performs username and password authentication if required.
- Connect Request: Requests the proxy server to establish a TCP connection to the destination host.
This sequence illustrates the multi-step SOCKS5 handshake and connection process.
Protocol Constants
| Field | Value | Description |
|---|---|---|
| Version | 0x05 | SOCKS Protocol Version 5 |
| Method: No Auth | 0x00 | No authentication required |
| Method: User/Pass | 0x02 | Username/Password authentication |
| CMD: Connect | 0x01 | Establish a TCP stream connection |
| ATYP: Domain | 0x03 | Target address is a domain name |
Sources: include/HXLibs/net/protocol/proxy/Socks5Proxy.hpp:41-167
HTTP Proxy Implementation
The HttpProxy class routes traffic using standard HTTP methods. It differentiates between encrypted (HTTPS) and unencrypted (HTTP) target traffic.
Tunneling Logic
- HTTPS Targets: Uses the
CONNECTmethod to establish an opaque TCP tunnel through the proxy. - HTTP Targets: Uses the
GETmethod with the full target URL.
The flowchart details the decision logic for HTTP vs. HTTPS tunneling.
Sources: include/HXLibs/net/protocol/proxy/HttpProxy.hpp:43-69
Integration with HttpClient
Proxy settings are configured via HttpClientOptions and passed to the client during instantiation.
Configuration
You specify the proxy type and its URL within the options structure. The HttpClient then manages the lifecycle of the proxy connection during its internal makeSocket routine.
// Example: Using a SOCKS5 proxy
HttpsClient cli{HttpClientOptions{
ProxyType<Socks5Proxy>{"socks5://127.0.0.1:2333"}
}};
Internal Flow in HttpClient
When HttpClient::makeSocket is called:
- The client resolves the address of the proxy server (not the target).
- A TCP connection is established to the proxy.
- If a proxy is configured, the
proxy.connect(proxyUrl, targetUrl)method is awaited. - Once the proxy connection succeeds, the client proceeds with TLS handshakes (if HTTPS) or direct HTTP requests.
Sources: include/HXLibs/net/client/HttpClient.hpp:607-640, include/HXLibs/net/client/HttpClientOptions.hpp:33-66, examples/Client/01_socks5_proxy_cli.cpp:21-25
Summary
Proxy support in HXLibs is implemented as an extensible layer within the net module. By abstracting protocol-specific handshakes into dedicated classes (Socks5Proxy, HttpProxy), the project allows HttpClient to support complex network topologies while maintaining a consistent asynchronous API for the user.
Sources: include/HXLibs/net/protocol/proxy/Proxy.hpp, include/HXLibs/net/client/HttpClient.hpp