Gumdrop SOCKS Proxy Server & Client

← Back to Main Page

Gumdrop provides a SOCKS proxy server and a composable SOCKS client for tunneling other protocol handlers through a proxy. The server supports SOCKS4, SOCKS4a, and SOCKS5 (RFC 1928), including username/password authentication (RFC 1929) and GSS-API authentication (RFC 1961). CONNECT, BIND, and UDP ASSOCIATE are implemented with asynchronous relaying consistent with the rest of the framework.

Contents

• Architecture
• Configuration
• SOCKSService properties
• SOCKSListener properties
• Common listener options
• Custom authorization
• Client API
• Telemetry

Architecture

A SOCKSService owns one or more SOCKSListener instances. Each accepted connection is handled by SOCKSProtocolHandler, which negotiates the SOCKS version, performs optional authentication, and establishes relays via SOCKSRelay, SOCKSBindRelay, or SOCKSUDPRelay as appropriate. Subclasses of SOCKSService may supply ConnectHandler and BindHandler implementations for application-level authorization.

• org.bluezoo.gumdrop.socks.SOCKSService — abstract base; destination filtering, relay limits, idle timeout
• org.bluezoo.gumdrop.socks.DefaultSOCKSService — default proxy (accept CONNECT/BIND that pass filtering; optional realm for SOCKS5)
• org.bluezoo.gumdrop.socks.SOCKSListener — TCP listener; defaults to port 1080 (plaintext) or 1081 (TLS)
• org.bluezoo.gumdrop.socks.client.SOCKSClientHandler — wraps another ProtocolHandler and tunnels it through a SOCKS proxy
• org.bluezoo.gumdrop.socks.client.SOCKSClientConfig — version preference, credentials, handshake timeout

Configuration

Minimal proxy (no authentication)

<service id="socks" class="org.bluezoo.gumdrop.socks.DefaultSOCKSService">
    <listener class="org.bluezoo.gumdrop.socks.SOCKSListener" port="1080"/>
</service>

With realm (SOCKS5 username/password)

<realm id="socksRealm" class="org.bluezoo.gumdrop.auth.BasicRealm">
    <property name="href" path="realm-socks.xml"/>
</realm>

<service id="socks" class="org.bluezoo.gumdrop.socks.DefaultSOCKSService">
    <property name="realm" ref="#socksRealm"/>
    <listener class="org.bluezoo.gumdrop.socks.SOCKSListener" port="1080"/>
</service>

When a realm is set on the service, it is applied to each SOCKSListener that does not already define its own realm. SOCKS5 clients must complete RFC 1929 username/password authentication. SOCKS4 carries an unauthenticated userid field in the request only.

TLS (sockss)

<service id="socks" class="org.bluezoo.gumdrop.socks.DefaultSOCKSService">
    <listener class="org.bluezoo.gumdrop.socks.SOCKSListener"
            port="1081" secure="true">
        <property name="keystore-file" path="keystore.p12"/>
        <property name="keystore-pass" value="secret"/>
    </listener>
</service>

If no port is set, the listener uses 1080 for cleartext and 1081 when secure="true".

Destination filtering and relay limits

<service id="socks" class="org.bluezoo.gumdrop.socks.DefaultSOCKSService">
    <property name="allowed-destinations">203.0.113.0/24,2001:db8::/32</property>
    <property name="blocked-destinations">127.0.0.0/8,::1/128</property>
    <property name="max-relays" value="1000"/>
    <property name="relay-idle-timeout" value="5m"/>
    <listener class="org.bluezoo.gumdrop.socks.SOCKSListener" port="1080"/>
</service>

blocked-destinations is evaluated first; then, if allowed-destinations is set, the destination must match an allow rule. max-relays caps concurrent relay sessions (0 = unlimited). relay-idle-timeout accepts suffixes ms, s, m, h (alternatively set relay-idle-timeout-ms as a long value in milliseconds).

SOCKSService properties

SOCKSListener properties

To configure Kerberos from code, use SOCKSListener.configureGSSAPI(Path keytabPath, String servicePrincipal), which constructs a GSSAPIServer for that listener.

Common listener options

TLS and transport settings (secure, keystore-file, keystore-pass, need-client-auth, cipher-suites, named-groups), timeouts (idle-timeout, read-timeout, connection-timeout), bind addresses (addresses), rate limiting (rate-limit, max-connections-per-ip, max-auth-failures, auth-lockout-time), CIDR access control (allowed-networks, blocked-networks), and max-net-in-size are inherited from Listener / TCPListener and behave like other TCP-based services. See Security and main documentation (UNIX domain sockets, TLS).

Custom authorization

Subclass SOCKSService and override createConnectHandler(TCPListener) and/or createBindHandler(TCPListener) to install ConnectHandler / BindHandler callbacks that approve or reject individual requests using ConnectState and BindState (see org.bluezoo.gumdrop.socks.handler). Returning null keeps the default behaviour (accept after filtering and relay limits).

Client API

Use SOCKSClientHandler as the outer handler when connecting with ClientEndpoint to the proxy; it performs the SOCKS handshake then delegates to your inner protocol handler (for example SMTP or HTTP client handlers).

// Connect to smtp.example.com:587 via SOCKS proxy at proxy:1080
ClientEndpoint client = new ClientEndpoint(factory, "proxy", 1080);
client.connect(new SOCKSClientHandler(
    "smtp.example.com", 587,
    new SMTPClientProtocolHandler(callback)));

// With SOCKS5 username/password
SOCKSClientConfig config = new SOCKSClientConfig("user", "pass");
client.connect(new SOCKSClientHandler(
    "smtp.example.com", 587, config,
    new SMTPClientProtocolHandler(callback)));

SOCKSClientConfig exposes version (AUTO, SOCKS4, SOCKS5), username / password, and handshake-timeout-ms (default 30 s).

Telemetry

When a TelemetryConfig is attached to the listener, SOCKSServerMetrics records counters and histograms for connections, CONNECT/BIND/UDP ASSOCIATE requests, relays, bytes, authentication outcomes, and blocked destinations. See Telemetry for OTLP setup.

← Back to Main Page | MQTT | Security | Telemetry

Gumdrop SOCKS Proxy Server & Client