Crate tor_socksproto

tor-socksproto

Implements SOCKS in the flavors provided by Tor.

Overview

SOCKS is an old and somewhat janky protocol for telling a TCP proxy where to connect. Versions 4, 4a, and 5 are sometimes encountered in the wild.

The tor-socksproto crate tries to hide the actual details of the protocol, and expose a stateful handshake type that eventually provides a SocksRequest or an error. It is part of Arti, a project to implement Tor in Rust. At present, it is only used to provide a SOCKS proxy over the Tor network, but eventually it may be used to implement support for connecting to the Tor network over a SOCKS proxy.

This crate may be a good choice for you if you need a SOCKS implementation that “behaves like Tor”, but otherwise it is probably better to use some other SOCKS crate.

For more information about SOCKS:

• SOCKS5 (which is preferred) is specified in RFC 1928, and see also RFC 1929 for Username/Password authentication in SOCKS5.
• The wikipedia article is the best surviving documentation for SOCKS4 and SOCKS4a.
• See socks-extensions.txt for a description of Tor’s extensions and restrictions on the SOCKS protocol.

Design notes

Arti uses this crate instead of some other SOCKS implementation, for two reasons:

• First, because we need to support Tor SOCKS extensions.
• Second, and because we sometimes need to see particular details of the individual handshakes that most other SOCKS implementations don’t expose. (For example, if we are told to connect to a raw IP address, the type of the handshake can help us guess whether that IP address came from a DNS response–in which case we should warn about a possible DNS leak.)

Currently, tor-socksproto does no networking code: it only implements the server (proxy) side of the SOCKS handshake by handling a series of bytes. We may (or may not) want to add network functionality to this crate or elsewhere in the future. We’ll definitely want to add client functionality.

Possibly, this approach will prove useful for other uses. If it does, We can put the tor-only functionality behind a Cargo build feature, so that others can use this crate more safely.

License: MIT OR Apache-2.0

Re-exports

pub use SocksProxyHandshake as SocksHandshake;proxy-handshake

Structs

Action

An action to take in response to a SOCKS handshake message.

Bufferproxy-handshake or client-handshake

An input buffer containing maybe some socks data

Finishedproxy-handshake or client-handshake

A completed handshake

PreciseReadsproxy-handshake or client-handshake

Marker indicating precise reads

RecvStepproxy-handshake or client-handshake

Next step - details for reading from the peer

SocksClientHandshakeclient-handshake

The client (initiator) side of a SOCKS handshake.

SocksCmd

Command from the socks client telling us what to do.

SocksHostname

A hostname for use with SOCKS. It is limited in length.

SocksProxyHandshakeproxy-handshake

The Proxy (responder) side of an ongoing SOCKS handshake.

SocksReply

The reply from a SOCKS proxy.

SocksRequest

A completed SOCKS request, as negotiated on a SOCKS connection.

SocksStatus

Possible reply status values from a SOCKS5 handshake.

Truncated

Error type indicating that an input was incomplete, and could not be processed.

Enums

Error

An error that occurs while negotiating a SOCKS handshake.

NextStepproxy-handshake or client-handshake

Next step to take in the handshake

SocksAddr

An address sent or received as part of a SOCKS handshake

SocksAuth

Provided authentication from a SOCKS handshake

SocksVersion

A supported SOCKS version.

Constants

SOCKS_BUF_LEN

Suggested buffer length for socks handshakes.

Traits

Handshakeproxy-handshake or client-handshake

Handshake

ReadPrecisionproxy-handshake or client-handshake

Markers indicating whether we’re allowing read-ahead,

Type Aliases

Result

A Result type for the tor_socksproto crate.

TResult

A Result type for the tor_socksproto crate, including the possibility of a truncated message.