go-socks5

The go-socks5 package implements the SOCKS5 protocol to route traffic through an intermediate proxy layer. Key features include:

• Protocol Support: SOCKS5 server support, including TCP/UDP and IPv4/IPv6.
• Authentication: "No Auth" mode and optional User/Password authentication with user address limits.
• Commands: Support for CONNECT and ASSOCIATE commands (Note: BIND command support is currently a TODO).
• Extensibility:
  • Granular command filtering via rules.
  • Custom DNS resolution.
  • Custom goroutine pools.
  • Buffer pool design with optional custom buffer pools.
  • Custom logging.

Install the package using go get and then import it into your Go project.

    go get github.com/things-go/go-socks5

import "github.com/things-go/go-socks5"

The go-socks5 server is configured using the Option type, which follows the functional options pattern. You can pass multiple Option functions to the server constructor to customize its behavior, such as authentication, name resolution, logging, and request handling. If an option is not provided, the server uses sensible defaults (e.g., io.Discard for logging, DNSResolver for name resolution, and NewPermitAll for rules).

// Example of how options are typically applied to a server
// Note: The exact constructor (e.g., NewServer) is assumed based on the Option pattern
server := NewServer(socks5.WithLogger(myLogger), socks5.WithAuthMethods(myAuthMethods))

The RuleSet interface allows you to provide custom logic to allow or prohibit specific SOCKS5 actions (commands). By implementing the Allow method, you can inspect a *Request and decide whether to permit the connection based on the command type (Connect, Bind, or Associate).

type RuleSet interface {
	Allow(ctx context.Context, req *Request) (context.Context, bool)
}

The AuthContext is returned by an Authenticator upon a successful handshake. It encapsulates the state of the authenticated session:

• Method: The uint8 authentication method code used.
• Payload: A map[string]string containing authentication data. For UserPassAuthenticator, this map contains the keys "username" and "password".

type AuthContext struct {
	Method uint8
	Payload map[string]string
}

You can initialize a SOCKS5 server using socks5.NewServer. The server can be configured with options like a custom logger. Use server.ListenAndServe(network, address) to start the proxy. In the example below, the server listens on localhost:8000 using the tcp network.

package main

import (
	"log"
	"os"

	"github.com/things-go/go-socks5"
)

func main() {
	// Create a SOCKS5 server
	server := socks5.NewServer(
		socks5.WithLogger(socks5.NewLogger(log.New(os.Stdout, "socks5: ", log.LstdFlags))),
	)

	// Create SOCKS5 proxy on localhost port 8000
	if err := server.ListenAndServe("tcp", ":8000"); err != nil {
		panic(err)
	}
}

The SendReply function is used to send a SOCKS5 response message back to the client. It takes an io.Writer, a reply status code (rep), and an optional net.Addr (used for statute.RepSuccess to provide the bound address, such as in ASSOCIATE commands).

Reply statuses are defined in the statute package (e.g., statute.RepSuccess, statute.RepHostUnreachable, statute.RepConnectionRefused).

// Example: Sending a success reply with a specific bound address
err := socks5.SendReply(writer, statute.RepSuccess, boundAddr)

To implement custom authentication logic in go-socks5, you must satisfy the Authenticator interface. The interface requires two methods:

1. GetCode() uint8: Returns the SOCKS5 authentication method code (e.g., statute.MethodNoAuth or statute.MethodUserPassAuth).
2. Authenticate(reader io.Reader, writer io.Writer, userAddr string) (*AuthContext, error): Handles the handshake logic. It reads the client's credentials from the reader, writes the server's response to the writer, and returns an AuthContext containing the authentication method and a Payload map of credentials if successful.

If authentication fails, you should write the appropriate failure byte to the writer and return an error.

type Authenticator interface {
	Authenticate(reader io.Reader, writer io.Writer, userAddr string) (*AuthContext, error)
	GetCode() uint8
}

The ListenAndServeTLS method creates a TLS-encrypted listener and serves connections. This is useful for wrapping the SOCKS5 protocol in a TLS layer.

Parameters:

• network: The network type (e.g., "tcp").
• addr: The address to listen on.
• c: A *tls.Config object defining the TLS settings.

// Example with TLS
tlsConfig := &tls.Config{
    // your TLS configuration
}
err := server.ListenAndServeTLS("tcp", ":1080", tlsConfig)
if err != nil {
    log.Fatal(err)
}

The package provides several helper functions to quickly create common RuleSet configurations using PermitCommand:

• NewPermitNone(): Disallows all types of connections.
• NewPermitAll(): Allows all types of connections.
• NewPermitConnAndAss(): Allows only Connect and Associate connections.

// Disallow everything
rules := socks5.NewPermitNone()

// Allow everything
rules := socks5.NewPermitAll()

// Allow only Connect and Associate
rules := socks5.NewPermitConnAndAss()