Implementing a SOCKS5 Proxy with Rust

The first step toward becoming familiar with a language might be writing a proxy with it. After studying Rust syntax for a long time, I still had little opportunity to use it at work, so I had to create a need for it myself. I hope to find a job writing Rust in the future, or one that gives me the freedom to learn new things.

What are this proxy’s features?

  • Based on Rust

The main purpose is to practice writing Rust. Rust is also safe and efficient.

  • Based on TLS WebSocket

Getting past the mysterious wall requires an encrypted connection; otherwise, it can easily get killed. A common approach, like the one used by Shadowsocks, is to define a custom encryption protocol, but that is rather troublesome. To keep things simple, I used TLS WebSocket directly for this purpose.

  • Pooled WebSocket connections

The benefits of connection pooling hardly need explaining. Eliminating connection establishment time makes the proxy faster.

The overall proxy flow looks like this:

Rust proxy pipeline

Source code: https://github.com/suikammd/rust-proxy

Prerequisites

(Not required)

Overall client-side flow

Proxy client

Code design

The connection between the browser and the client is a regular SOCKS5 connection, and the connection between the server and the destination the browser wants to access is a regular TCP connection. Between the client and server, however, there are pooled WebSocket connections. There are four main things we need to do:

(1) Parse the SOCKS5 protocol to obtain the destination address the browser wants to access.

(2) Define custom packets. The same WebSocket connection corresponds to multiple SOCKS5 connections from the browser to the client. Therefore, when a new SOCKS5 connection is established, the server needs to know the address the browser wants to access (a Connect packet). When the SOCKS5 connection is closed, a termination packet needs to be sent (a Close packet), so that the server returns to the state of waiting for a Connect packet.

(3) Pool WebSocket connections, which involves implementing a general-purpose connection pool.

(4) Tokio provides a bidirectional copying method that requires the data structure to implement the AsyncRead + AsyncWrite traits. Because the WebSocketStream defined by tokio_tungstenite does not implement these two traits, we also need to implement them ourselves.

Parsing the SOCKS5 protocol

  • The browser and client agree on the protocol version and authentication method.
VER NMETHODS METHODS
1 1 1-255

VER: SOCKS version, which is 0x05 here.

NMETHODS: The number of METHODS.

METHODS: Authentication methods supported by the client.

  • The client selects one of the authentication methods specified by the browser and replies with it.
VER METHOD
1 1

METHOD: The authentication method selected by the client.

For now, this article uses 0x00 (meaning no authentication is required).

  • The browser sends a request message telling the client which address it wants to access.
VER CMD RSV ATYP DST.ADDR DST.PORT
1 1 0x00 1 Variable 2

CMD: SOCKS command code: 0x01 (Connect request), 0x02 (BIND request), or 0x03 (UDP relay).

RSV: Reserved byte, 0x00.

ATYP: Type of DST.ADDR: 0x01 (IPv4), 0x03 (domain name), or 0x04 (IPv6).

DST.ADDR: Destination address.

DST.PORT: Destination port.

  • After the client processes the address the browser wants to access, it returns the result to the browser.
VER REP RSV ATYP BND.ADDR BND.PORT
1 1 0x00 1 Variable 2

The content is almost the same as the browser’s request packet.

Custom packet structure

There are three types of packets sent from the client to the server: Connect packets (which tell the server the destination address the browser wants to access), Data packets (browser request data), and Close packets (which indicate that the SOCKS5 connection has been disconnected or has ended), as shown below.

1
2
3
4
5
6
7
8
9
10
11
pub enum Packet {
Connect(Addr),
Data(Vec<u8>),
Close(),
}

pub enum Addr {
IpV4(([u8; 4], u16)),
Domain((String, u16)),
IpV6(([u8; 16], u16)),
}

Incidentally, this repository is implemented using the tokio_tungstenite WebSocket library. Its design is unreasonable in many ways. For example, there is no way to reuse buffers. Consider the following code: when I construct a Binary packet, I need to pass in a Vec. Even if I pass in another kind of packet, it is converted into a Vec through bin.into(), effectively making another copy. It would be better to pass in a Vec directly. If I optimize the proxy later, I will consider rewriting this WebSocket library.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
pub enum Message {
/// A text WebSocket message
Text(String),
/// A binary WebSocket message
Binary(Vec<u8>),
/// A ping message with the specified payload
///
/// The payload here must have a length less than 125 bytes
Ping(Vec<u8>),
/// A pong message with the specified payload
///
/// The payload here must have a length less than 125 bytes
Pong(Vec<u8>),
/// A close message with the optional close frame.
Close(Option<CloseFrame<'static>>),
}

impl Message {
/// Create a new binary WebSocket message by converting to Vec<u8>.
pub fn binary<B>(bin: B) -> Message
where
B: Into<Vec<u8>>,
{
Message::Binary(bin.into())
}
}

Connection pool implementation

As the name suggests, a connection pool contains a large number of already established connections. Its value is beyond doubt in a proxy scenario where the remote endpoint is fixed. What functionality does our connection pool need? In short, it takes connections out of the pool and puts them back. To make the pool fast enough, however, we can optimize connection acquisition as follows: if there are no idle connections in the pool, we can put a waiter in the pool (actually the sending end of a channel). When someone finishes using a connection, they can hand it directly to this waiter. We also create a new connection at the same time, then use future::select to wait for either the waiter to receive a connection or the new connection to finish being created.

At this point, we can summarize the pool definition, which could look like this:

1
2
3
4
5
6
7
8
9
pub struct Pool<T> {
inner: Arc<Mutex<Inner<T>>>,
}

pub struct Inner<T> {
idle: Vec<T>,
waiters: VecDeque<oneshot::Sender<T>>,
max_idle: usize,
}

idle holds idle connections, waiters holds the waiters inserted when requesting a connection from the pool, and max_idle is the maximum number of idle connections.

(1) What does this pool need to do?

  • Manage idle connections: this is essentially just a vec.

  • Take a connection out of the pool.

There are two cases:

(1) If idle has an available connection, pop an idle connection directly from idle.

(2) Push a new waiter into waiters, and use the make_service passed into the get method to create a new connection at the same time. Then use future::select to wait for either someone to return a used connection to the waiter or the new connection to finish being created. There is also an interesting optimization here: if someone returns a used connection to the waiter first, wouldn’t half-creating the new connection be wasteful? Not a problem. We can use tokio::spwan to continue creating the new connection in the background, then put the newly created connection into idle.

The returned data structure is defined as follows: one field is the connection itself, and the other is a weak reference to the pool. Why does inner need to be an Option? Because this makes it convenient to take the connection out without triggering Pooled‘s destructor, and we can insert it back after use. Why do we need to hold a weak reference to the pool? Because we need to know which pool to return the connection to.

1
2
3
4
pub struct Pooled<T> {
pub inner: Option<T>,
pool: Weak<Mutex<Inner<T>>>,
}

By now, you can probably imagine how connections are returned to the pool.

  • Return a connection to the pool.

When a connection is no longer being used, we do not close it. Instead, its destructor returns it to the pool. Therefore, we can implement the Drop trait for Pooled and call the pool’s put method in drop to actually return the connection to the pool.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
impl<T> Drop for Pooled<T> {
fn drop(&mut self) {
if self.inner.is_none() {
info!("inner drop is not some?");
return;
}
let t = self.inner.take().unwrap();
if let Some(pool) = self.pool.upgrade() {
if let Ok(mut pool) = pool.lock() {
pool.put(t);
info!("successfully put ws stream back to pool")
}
}
}
}

The acquisition logic tells us what returning a connection to the pool should do. First, check whether there is a waiter. If there is, give the connection directly to the waiter; if not, put the connection back into idle.

  • Detect connection status.

If a connection in the pool dies and we do not detect it promptly, the client may receive a dead connection, resulting in a terrible user experience. Therefore, we also need to periodically check the status of connections in the pool. To do this, we need to define a Poolable trait and remove a connection from the pool if it is not reuseable.

1
2
3
4
pub trait Poolable {
// check if the connection is opened
fn reuseable(&self) -> bool;
}

Of course, this is actually a fairly general-purpose implementation, but the code here does not accomplish this yet. The underlying layer cannot detect the connection status, so the upper layer still needs to actively perform health checks. That logic has not been implemented yet.

Implementing AsyncRead + AsyncWrite for WebSocketStream

There are many aspects of tokio_tungstenite‘s design that seem strange to me. On the client side, whether you want to establish a TLS or non-TLS connection, you always get WebSocketStream<MaybeTlsStream<TcpStream>>, while the server always gets WebSocketStream<TlsStream<TcpStream>>. Fortunately, both MaybeTlsStream and TlsStream implement AsyncRead and AsyncWrite, so we do not have to implement these traits separately for the client and server connections.

For AsyncRead, we need to implement the poll_read method.

1
2
3
4
5
6
7
pub trait AsyncRead {
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut ReadBuf<'_>,
) -> Poll<io::Result<()>>;
}

For AsyncWrite, we need to implement poll_write, poll_flush, and poll_shutdown.

1
2
3
4
5
6
7
8
9
10
11
pub trait AsyncWrite {
fn poll_write(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &[u8],
) -> Poll<Result<usize, io::Error>>;

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>>;

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>>;
}

There are two points to note. When copy_bidirectional completes, it executes poll_shutdown. Since we need to reuse the underlying connection, we should not actually close the connection. Instead, we send a Close packet (telling the peer that the SOCKS5 connection it carried has ended and that it can accept a new SOCKS connection), then return Poll::Ready(Ok(())). The other point is that the usize length returned by poll_write must not exceed the length of buf (see another post, An Interesting Debugging Journey, for the specific reason).

Summary

Writing a working proxy in Rust is still quite easy, but making it sufficiently robust is difficult. There are many details to consider, especially error handling when connections behave abnormally. Next, I want to prevent dead connections from remaining in the connection pool. This requires both actively checking connection health and retrying on the client side (when the underlying connection behaves abnormally, the upper layer triggers a limited number of retries).

Author: suikammd
Link: https://suikammd.github.io/2021/09/11/rust-proxy/
Copyright Notice: All articles in this blog are licensed under CC BY-NC-SA 4.0 unless stating additionally.