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

> Learn how to set up SOCKS5 proxy with authentication on the MasterDnsVPN client. Configure SOCKS5_AUTH, SOCKS5_USER, and SOCKS5_PASS for secure connectivity.

- Repository: [Amin Mahmoudi/MasterDnsVPN](https://github.com/masterking32/MasterDnsVPN)
- Tags: how-to-guide
- Published: 2026-05-10

---

**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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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`):

```toml
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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/config/client.go):

```bash
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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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:

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

```

For manual testing of the handshake process, use `netcat`:

```bash

# 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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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`](https://github.com/masterking32/MasterDnsVPN/blob/main/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`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/config/client.go) validates these constraints during client initialization.