How to Set Up SOCKS5 Proxy with Authentication on the MasterDnsVPN Client

The MasterDnsVPN client supports built-in SOCKS5 authentication through three configuration fields—SOCKS5_AUTH, SOCKS5_USER, and SOCKS5_PASS—which enable username/password verification in the SOCKS5 handshake handler.

The MasterDnsVPN client, available in the masterking32/MasterDnsVPN repository, provides a lightweight SOCKS5 proxy implementation with optional credential-based access control. When you set up SOCKS5 proxy with authentication on the MasterDnsVPN client, you secure your local proxy endpoint by requiring valid username and password combinations before allowing traffic forwarding through the VPN tunnel.

Configuration Fields in ClientConfig

The authentication parameters are defined in the ClientConfig struct located in internal/config/client.go (lines 26-38). Three fields control the behavior:

• SOCKS5_AUTH: Boolean flag that enables authentication when set to true. Defaults to false.
• SOCKS5_USER: Username string (maximum 255 bytes). Defaults to "master_dns_vpn".
• SOCKS5_PASS: Password string (maximum 255 bytes). Defaults to "master_dns_vpn".

These values are validated during configuration finalization in the finalizeClientConfig function (lines 62-66 of the same file).

Enabling Authentication via TOML Configuration

Create or modify your client configuration file to enable credential-based access. The client listens on LISTEN_IP and LISTEN_PORT (defaulting to 127.0.0.1:18000):

PROTOCOL_TYPE = "SOCKS5"
LISTEN_IP = "127.0.0.1"
LISTEN_PORT = 18000

SOCKS5_AUTH = true
SOCKS5_USER = "alice"
SOCKS5_PASS = "s3cr3t"

Save this as client_config.toml and start the client. The proxy now requires the username alice and password s3cr3t before establishing connections.

Command-Line Override Options

You can bypass the configuration file by passing flags directly to the binary. The flag binding is handled by NewClientConfigFlagBinder in internal/config/client.go:

masterdnsvpn-client \
    -config client_config.toml \
    -SOCKS5_AUTH=true \
    -SOCKS5_USER=alice \
    -SOCKS5_PASS=s3cr3t

Authentication Implementation in socks_manager.go

When SOCKS5_AUTH is enabled, the HandleSOCKS5 method in internal/client/socks_manager.go selects the username/password authentication method (0x02) during the SOCKS5 handshake. The implementation (lines 60-75 and 124-132) validates supplied credentials against your configured values. If authentication fails, the client returns a 0x01 failure reply and may ban the offending IP via the integrated rate-limiter.

Testing the SOCKS5 Proxy Connection

Verify your setup using curl with SOCKS5 protocol support:

curl -x socks5h://alice:s3cr3t@127.0.0.1:18000 https://example.com

For manual testing of the handshake process, use netcat:

# Send SOCKS5 greeting requesting username/password auth (method 0x02)

printf '\x05\x01\x02' | nc 127.0.0.1 18000

# Server responds with chosen method (0x02)

# Send credentials: VER=1, ULEN=5, USER="alice", PLEN=6, PASS="s3cr3t"

printf '\x01\x05alice\x06s3cr3t' | nc 127.0.0.1 18000

A successful authentication returns 0x00 from the server. Incorrect credentials result in a 0x01 authentication failure response.

Summary

• The MasterDnsVPN client stores SOCKS5 authentication settings in ClientConfig within internal/config/client.go.
• Enable authentication by setting SOCKS5_AUTH = true and defining custom SOCKS5_USER and SOCKS5_PASS values (max 255 bytes each).
• The HandleSOCKS5 function in internal/client/socks_manager.go implements the username/password handshake method (0x02) and validates credentials against your configuration.
• You can configure these options via TOML files or command-line flags using the flag binder in the client configuration module.

Frequently Asked Questions

What is the default SOCKS5 authentication setting in MasterDnsVPN?

By default, SOCKS5_AUTH is set to false in the ClientConfig struct, allowing anonymous connections. The default credentials are both set to "master_dns_vpn" but are only enforced when authentication is explicitly enabled by setting the field to true.

Can I disable SOCKS5 authentication after enabling it?

Yes. You can disable authentication by setting SOCKS5_AUTH = false in your TOML configuration or by passing -SOCKS5_AUTH=false as a command-line flag when starting the client. The change takes effect immediately on the next client restart without requiring recompilation.

What happens if a client provides wrong credentials?

The SOCKS5 server replies with authentication failure code 0x01 and terminates the connection. According to the implementation in internal/client/socks_manager.go, the offending IP address may be temporarily banned via the rate-limiter depending on your security configuration.

Are there length restrictions for SOCKS5 usernames and passwords?

Yes, both SOCKS5_USER and SOCKS5_PASS must not exceed 255 bytes each, conforming to the SOCKS5 protocol specification. The finalizeClientConfig function in internal/config/client.go validates these constraints during client initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}