Sox

Sox is a full-featured SOCKS4 and SOCKS5 library for the Crystal programming language. It provides both client and server implementations, supporting all major SOCKS5 commands (CONNECT, BIND, UDP ASSOCIATE) and SOCKS4 (CONNECT) with SOCKS4a domain name resolution. The library is production-ready, thoroughly tested, and compatible with Crystal 1.20.2.

Features

• SOCKS5
  • Address types: IPv4, IPv6, Domain (FQDN)
  • Authentication: No‑Authentication, Username/Password (RFC 1929)
  • Commands: CONNECT, BIND, UDP ASSOCIATE
• SOCKS4 / SOCKS4a
  • CONNECT command
  • Domain name resolution (SOCKS4a)
• Server
  • Listens on any interface/port
  • Supports all SOCKS4 and SOCKS5 commands
  • Pluggable authentication handlers
• Client
  • Simple API for TCP connections (Sox::Client)
  • SOCKS-aware TCP socket (Sox::Socket)
  • UDP association with header wrapping (Sox::UDP::Socket)
• Full test suite – 14 examples, all passing

---

Installation

Add this to your application's shard.yml:

dependencies:
  sox:
    github: okavatti/sox # Replace with your repository

Then run:

shards install

---

Usage

Client: TCP CONNECT

To open a TCP connection through a SOCKS proxy:

require "sox"

# Connect to example.com via a SOCKS5 proxy on localhost:1080
client = Sox::Client.new("127.0.0.1", 1080, version: Sox::VERSION_5)
socket = client.connect("example.com", 80)

# Send an HTTP request
socket.write("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n")
response = socket.gets_to_end
puts response
socket.close

With username/password authentication:

client = Sox::Client.new("127.0.0.1", 1080,
                         username: "myuser", password: "mypass")
socket = client.connect("example.com", 80)

Using SOCKS4:

client = Sox::Client.new("127.0.0.1", 1080, version: Sox::VERSION_4)
socket = client.connect("example.com", 80)

Client: UDP ASSOCIATE

For UDP‑based protocols (e.g., DNS over UDP):

client = Sox::Client.new("127.0.0.1", 1080)
udp_socket = client.udp_associate

# Send a datagram to a DNS server via the SOCKS relay
udp_socket.send("Hello UDP".to_slice, "8.8.8.8", 53)

# Receive a reply
data, addr, port = udp_socket.receive(1024)
puts String.new(data)
udp_socket.close

The UDP::Socket automatically wraps datagrams with the SOCKS5 header and strips it on receive.

Server: Standalone SOCKS Proxy

To run a SOCKS4/5 server:

require "sox"

server = Sox::Server.new("0.0.0.0", 1080)
spawn { server.start }

With username/password authentication:

auth = ->(method : Sox::AuthMethod, user : String?, pass : String?) do
  method == Sox::AuthMethod::UsernamePassword &&
  user == "admin" && pass == "secret"
end

server = Sox::Server.new("0.0.0.0", 1080, auth_handler: auth)
spawn { server.start }

SOCKS4 user‑ID validation:

v4_auth = ->(user_id : String, addr : String) do
  user_id == "trusted"
end

server = Sox::Server.new("0.0.0.0", 1080, v4_auth_handler: v4_auth)
spawn { server.start }

Direct SOCKS Socket

For low‑level control, use Sox::Socket:

sock = Sox::Socket.open("127.0.0.1", 1080, "example.com", 80)
sock.write("GET / HTTP/1.0\r\n\r\n")
puts sock.gets_to_end
sock.close

---

Development

Running Tests

The test suite requires no external dependencies; it spins up local echo servers and a SOCKS proxy automatically.

crystal spec

All 14 examples should pass. The suite includes:

• SOCKS4 request/response encoding/decoding
• SOCKS5 request/response encoding/decoding
• TCP CONNECT (SOCKS4 & SOCKS5)
• Username/Password authentication (pass and fail)
• Server CONNECT & BIND
• UDP ASSOCIATE

Building the Library

This is a library, not an executable. To use it in your project, simply require sox after installing the shard.

Code Structure

• src/sox.cr – main module, enums, exceptions
• src/socks4.cr – SOCKS4 request/response structs
• src/socks5.cr – SOCKS5 request/response structs
• src/request.cr – unified client request executor
• src/socket.cr – SOCKS‑aware TCPSocket
• src/sox/client.cr – high‑level client API
• src/sox/server.cr – multi‑protocol server
• src/sox/udp.cr – UDP relay engine
• src/sox/udp/socket.cr – UDP wrapper for client use

Contributing

Bug reports and pull requests are welcome. Please ensure all tests pass before submitting.

---

License

This library is distributed under the MIT License.

---

Acknowledgements

Based on the original jkthorne/sox project. This version adds full SOCKS4 support, robust authentication, a working server, comprehensive tests, and modern Crystal practices.

---

Additional Resources

• SOCKS5 Protocol (RFC 1928)
• SOCKS4 Protocol
• Username/Password Authentication for SOCKS5 (RFC 1929)

---