Lines
75.86 %
Functions
44.83 %
Branches
100 %
//! Structures that represent SOCKS messages
use crate::{Error, Result};
use caret::caret_int;
use std::fmt;
use std::net::IpAddr;
#[cfg(feature = "arbitrary")]
use std::net::Ipv6Addr;
use tor_error::bad_api_usage;
use arbitrary::{Arbitrary, Result as ArbitraryResult, Unstructured};
/// A supported SOCKS version.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
#[non_exhaustive]
pub enum SocksVersion {
/// Socks v4.
V4,
/// Socks v5.
V5,
}
/// We tried to convert something other than '4' or '5' to a SOCKS version.
#[derive(Copy, Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error("{0} is not a recognized socks version")]
#[allow(clippy::exhaustive_structs)]
pub struct InvalidSocksVersion(pub u8);
impl TryFrom<u8> for SocksVersion {
// Note: This is not and should not be `Error::BadProtocol`!
// See the documentation on that variant for discussion of why.
type Error = InvalidSocksVersion;
fn try_from(v: u8) -> std::result::Result<SocksVersion, InvalidSocksVersion> {
match v {
4 => Ok(SocksVersion::V4),
5 => Ok(SocksVersion::V5),
// Note that we do *not* return BadProtocol in this case.
// BadProtocol is only for the case when the first byte
// of the SOCKS handshake is invalid.
_ => Err(InvalidSocksVersion(v)),
impl fmt::Display for SocksVersion {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
SocksVersion::V4 => write!(f, "socks4"),
SocksVersion::V5 => write!(f, "socks5"),
/// A completed SOCKS request, as negotiated on a SOCKS connection.
///
/// Once this request is done, we know where to connect. Don't
/// discard this object immediately: Use it to report success or
/// failure.
#[derive(Clone, Debug)]
#[cfg_attr(test, derive(PartialEq, Eq))]
pub struct SocksRequest {
/// Negotiated SOCKS protocol version.
version: SocksVersion,
/// The command requested by the SOCKS client.
cmd: SocksCmd,
/// The target address.
addr: SocksAddr,
/// The target port.
port: u16,
/// Authentication information.
/// (Tor doesn't believe in SOCKS authentication, since it cannot
/// possibly secure. Instead, we use it for circuit isolation.)
auth: SocksAuth,
impl<'a> Arbitrary<'a> for SocksRequest {
fn arbitrary(u: &mut Unstructured<'a>) -> ArbitraryResult<Self> {
let version = SocksVersion::arbitrary(u)?;
let cmd = SocksCmd::arbitrary(u)?;
let addr = SocksAddr::arbitrary(u)?;
let port = u16::arbitrary(u)?;
let auth = SocksAuth::arbitrary(u)?;
SocksRequest::new(version, cmd, addr, port, auth)
.map_err(|_| arbitrary::Error::IncorrectFormat)
/// An address sent or received as part of a SOCKS handshake
#[derive(Clone, Debug, PartialEq, Eq)]
#[allow(clippy::exhaustive_enums)]
pub enum SocksAddr {
/// A regular DNS hostname.
Hostname(SocksHostname),
/// An IP address. (Tor doesn't like to receive these during SOCKS
/// handshakes, since they usually indicate that the hostname lookup
/// happened somewhere else.)
Ip(IpAddr),
impl<'a> Arbitrary<'a> for SocksAddr {
use std::net::Ipv4Addr;
let b = u8::arbitrary(u)?;
Ok(match b % 3 {
0 => SocksAddr::Hostname(SocksHostname::arbitrary(u)?),
1 => SocksAddr::Ip(IpAddr::V4(Ipv4Addr::arbitrary(u)?)),
_ => SocksAddr::Ip(IpAddr::V6(Ipv6Addr::arbitrary(u)?)),
})
fn size_hint(_depth: usize) -> (usize, Option<usize>) {
(1, Some(256))
/// A hostname for use with SOCKS. It is limited in length.
pub struct SocksHostname(String);
impl<'a> Arbitrary<'a> for SocksHostname {
String::arbitrary(u)?
.try_into()
(0, Some(255))
/// Provided authentication from a SOCKS handshake
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum SocksAuth {
/// No authentication was provided
NoAuth,
/// Socks4 authentication (a string) was provided.
Socks4(Vec<u8>),
/// Socks5 username/password authentication was provided.
Username(Vec<u8>, Vec<u8>),
caret_int! {
/// Command from the socks client telling us what to do.
pub struct SocksCmd(u8) {
/// Connect to a remote TCP address:port.
CONNECT = 1,
/// Not supported in Tor.
BIND = 2,
UDP_ASSOCIATE = 3,
/// Lookup a hostname, return an IP address. (Tor only.)
RESOLVE = 0xF0,
/// Lookup an IP address, return a hostname. (Tor only.)
RESOLVE_PTR = 0xF1,
/// Possible reply status values from a SOCKS5 handshake.
/// Note that the documentation for these values is kind of scant,
/// and is limited to what the RFC says. Note also that SOCKS4
/// only represents success and failure.
pub struct SocksStatus(u8) {
/// RFC 1928: "succeeded"
SUCCEEDED = 0x00,
/// RFC 1928: "general SOCKS server failure"
GENERAL_FAILURE = 0x01,
/// RFC 1928: "connection not allowable by ruleset"
/// (This is the only occurrence of 'ruleset' or even 'rule'
/// in RFC 1928.)
NOT_ALLOWED = 0x02,
/// RFC 1928: "Network unreachable"
NETWORK_UNREACHABLE = 0x03,
/// RFC 1928: "Host unreachable"
HOST_UNREACHABLE = 0x04,
/// RFC 1928: "Connection refused"
CONNECTION_REFUSED = 0x05,
/// RFC 1928: "TTL expired"
/// (This is the only occurrence of 'TTL' in RFC 1928.)
TTL_EXPIRED = 0x06,
/// RFC 1929: "Command not supported"
COMMAND_NOT_SUPPORTED = 0x07,
/// RFC 1929: "Address type not supported"
ADDRTYPE_NOT_SUPPORTED = 0x08,
/// Prop304: "Onion Service Descriptor Can Not be Found"
HS_DESC_NOT_FOUND = 0xF0,
/// Prop304: "Onion Service Descriptor Is Invalid"
HS_DESC_INVALID = 0xF1,
/// Prop304: "Onion Service Introduction Failed"
HS_INTRO_FAILED = 0xF2,
/// Prop304: "Onion Service Rendezvous Failed"
HS_REND_FAILED = 0xF3,
/// Prop304: "Onion Service Missing Client Authorization"
HS_MISSING_CLIENT_AUTH = 0xF4,
/// Prop304: "Onion Service Wrong Client Authorization"
HS_WRONG_CLIENT_AUTH = 0xF5,
/// "Onion service address is invalid"
/// (Documented in `tor.1` but not yet specified.)
HS_BAD_ADDRESS = 0xF6,
/// "Onion Service Introduction Timed Out"
HS_INTRO_TIMEOUT = 0xF7
impl SocksCmd {
/// Return true if this is a supported command.
fn recognized(self) -> bool {
matches!(
self,
SocksCmd::CONNECT | SocksCmd::RESOLVE | SocksCmd::RESOLVE_PTR
)
/// Return true if this is a command for which we require a port.
fn requires_port(self) -> bool {
SocksCmd::CONNECT | SocksCmd::BIND | SocksCmd::UDP_ASSOCIATE
impl SocksStatus {
/// Convert this status into a value for use with SOCKS4 or SOCKS4a.
#[cfg(feature = "proxy-handshake")]
pub(crate) fn into_socks4_status(self) -> u8 {
SocksStatus::SUCCEEDED => 0x5A,
_ => 0x5B,
/// Create a status from a SOCKS4 or SOCKS4a reply code.
#[cfg(feature = "client-handshake")]
pub(crate) fn from_socks4_status(status: u8) -> Self {
match status {
0x5A => SocksStatus::SUCCEEDED,
0x5B => SocksStatus::GENERAL_FAILURE,
0x5C | 0x5D => SocksStatus::NOT_ALLOWED,
_ => SocksStatus::GENERAL_FAILURE,
impl TryFrom<String> for SocksHostname {
type Error = Error;
fn try_from(s: String) -> Result<SocksHostname> {
if s.len() > 255 {
// This is only a limitation for Socks 5, but we enforce it in both
// cases, for simplicity.
Err(bad_api_usage!("hostname too long").into())
} else if contains_zeros(s.as_bytes()) {
// This is only a limitation for Socks 4, but we enforce it in both
Err(Error::Syntax)
} else {
Ok(SocksHostname(s))
impl AsRef<str> for SocksHostname {
fn as_ref(&self) -> &str {
self.0.as_ref()
impl SocksAuth {
/// Check whether this authentication is well-formed and compatible with the
/// provided SOCKS version.
/// Return an error if not.
fn validate(&self, version: SocksVersion) -> Result<()> {
SocksAuth::NoAuth => {}
SocksAuth::Socks4(data) => {
if version != SocksVersion::V4 || contains_zeros(data) {
return Err(Error::Syntax);
SocksAuth::Username(user, pass) => {
if version != SocksVersion::V5
|| user.len() > u8::MAX as usize
|| pass.len() > u8::MAX as usize
{
Ok(())
/// Return true if b contains at least one zero.
/// Try to run in constant time.
fn contains_zeros(b: &[u8]) -> bool {
use subtle::{Choice, ConstantTimeEq};
let c: Choice = b
.iter()
.fold(Choice::from(0), |seen_any, byte| seen_any | byte.ct_eq(&0));
c.unwrap_u8() != 0
impl SocksRequest {
/// Create a SocksRequest with a given set of fields.
/// Return an error if the inputs aren't supported or valid.
pub fn new(
) -> Result<Self> {
if !cmd.recognized() {
return Err(Error::NotImplemented(
format!("SOCKS command {}", cmd).into(),
));
if port == 0 && cmd.requires_port() {
auth.validate(version)?;
Ok(SocksRequest {
version,
cmd,
addr,
port,
auth,
/// Return the negotiated version (4 or 5).
pub fn version(&self) -> SocksVersion {
self.version
/// Return the command that the client requested.
pub fn command(&self) -> SocksCmd {
self.cmd
/// Return the 'authentication' information from this request.
pub fn auth(&self) -> &SocksAuth {
&self.auth
/// Return the requested port.
pub fn port(&self) -> u16 {
self.port
/// Return the requested address.
pub fn addr(&self) -> &SocksAddr {
&self.addr
impl fmt::Display for SocksAddr {
/// Format a string (a hostname or IP address) corresponding to this
/// SocksAddr.
SocksAddr::Ip(a) => write!(f, "{}", a),
SocksAddr::Hostname(h) => write!(f, "{}", h.0),
/// The reply from a SOCKS proxy.
#[derive(Debug, Clone)]
pub struct SocksReply {
/// The provided status code
status: SocksStatus,
/// The provided address, if any.
/// The provided port.
impl SocksReply {
/// Create a new SocksReply.
pub(crate) fn new(status: SocksStatus, addr: SocksAddr, port: u16) -> Self {
Self { status, addr, port }
/// Return the status code from this socks reply.
pub fn status(&self) -> SocksStatus {
self.status
/// Return the address from this socks reply.
/// The semantics of this address depend on the original socks command
/// provided; see the SOCKS specification for more information.
/// Note that some implementations (including Tor) will return `0.0.0.0` or
/// `[::]` to indicate "no address given".
/// The semantics of this port depend on the original socks command
#[cfg(test)]
mod test {
// @@ begin test lint list maintained by maint/add_warning @@
#![allow(clippy::bool_assert_comparison)]
#![allow(clippy::clone_on_copy)]
#![allow(clippy::dbg_macro)]
#![allow(clippy::mixed_attributes_style)]
#![allow(clippy::print_stderr)]
#![allow(clippy::print_stdout)]
#![allow(clippy::single_char_pattern)]
#![allow(clippy::unwrap_used)]
#![allow(clippy::unchecked_time_subtraction)]
#![allow(clippy::useless_vec)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::string_slice)] // See arti#2571
//! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
use super::*;
#[test]
fn display_sa() {
let a = SocksAddr::Ip(IpAddr::V4("127.0.0.1".parse().unwrap()));
assert_eq!(a.to_string(), "127.0.0.1");
let a = SocksAddr::Ip(IpAddr::V6("f00::9999".parse().unwrap()));
assert_eq!(a.to_string(), "f00::9999");
let a = SocksAddr::Hostname("www.torproject.org".to_string().try_into().unwrap());
assert_eq!(a.to_string(), "www.torproject.org");
fn ok_request() {
let localhost_v4 = SocksAddr::Ip(IpAddr::V4("127.0.0.1".parse().unwrap()));
let r = SocksRequest::new(
SocksVersion::V4,
SocksCmd::CONNECT,
localhost_v4.clone(),
1024,
SocksAuth::NoAuth,
.unwrap();
assert_eq!(r.version(), SocksVersion::V4);
assert_eq!(r.command(), SocksCmd::CONNECT);
assert_eq!(r.addr(), &localhost_v4);
assert_eq!(r.auth(), &SocksAuth::NoAuth);
fn bad_request() {
let e = SocksRequest::new(
SocksCmd::BIND,
);
assert!(matches!(e, Err(Error::NotImplemented(_))));
localhost_v4,
0,
assert!(matches!(e, Err(Error::Syntax)));
fn test_contains_zeros() {
assert!(contains_zeros(b"Hello\0world"));
assert!(!contains_zeros(b"Hello world"));