socks5

README

SOCKS 5

Report Bug | Request Feature

A fully featured implementation of the SOCKS 5 protocol in golang.

CONNECT	BIND	UDP ASSOCIATE
✅ - implemented	🛠 - in progress	✅ - implemented

Installation

go get github.com/growncondomi/socks5

Getting Started

Create your .go file. For example: main.go.

package main

import (
	"context"
	"log"
	"os/signal"
	"syscall"

	"github.com/growncondomi/socks5"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	srv := socks5.New()

	go func() {
		if err := srv.ListenAndServe(); err != nil {
			log.Fatal(err)
		}
	}()

	<-ctx.Done()

	if err := srv.Shutdown(); err != nil {
		log.Fatal(err)
	}
}

Run your server:

go run main.go

The following curl example shows how to use the proxy server:

curl -x socks5://127.0.0.1:1080 http://example.com

See the tests and examples for more information about package.

FAQ

• Why can't connect to socks proxy server?

  Not all applications and browsers support socks authentication or socks protocol. You may need extension for Chrome or another browser.

If you have any questions, you can ask in GitHub Discussions.

Note

• The proof of work for the UDP association was done using qBittorrent - a BitTorrent client.

Contributing

Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

Please follow the contribution guidelines.

References

• RFC 1928 SOCKS Protocol Version 5
• RFC 1929 Username/Password Authentication for SOCKS V5

Licenses

• All source code is licensed under the MIT License.

• Logo is based on the Go Gopher mascot originally designed by Egon Elbre and which is also licensed under the CC0 1.0 Universal License.

Documentation

Overview

Package socks5 a fully featured implementation of the SOCKS 5 protocol in golang.

Index

• Variables
• func RemoteAddressFromContext(ctx context.Context) (net.Addr, bool)
• func UsernameFromContext(ctx context.Context) (string, bool)
• type Command
• type Driver
• type Logger
• type Metrics
• type Option
  • func WithAllowCommands(commands ...Command) Option
  • func WithBlockListHosts(hosts ...string) Option
  • func WithDialTimeout(val time.Duration) Option
  • func WithDriver(val Driver) Option
  • func WithGetPasswordTimeout(val time.Duration) Option
  • func WithHost(val string) Option
  • func WithLogger(val Logger) Option
  • func WithMaxPacketSize(val int) Option
  • func WithMetrics(val Metrics) Option
  • func WithNatCleanupPeriod(val time.Duration) Option
  • func WithPacketWriteTimeout(val time.Duration) Option
  • func WithPasswordAuthentication() Option
  • func WithPort(val int) Option
  • func WithPublicIP(val net.IP) Option
  • func WithReadTimeout(val time.Duration) Option
  • func WithRules(val Rules) Option
  • func WithStaticCredentials(val map[string]string) Option
  • func WithStore(val Store) Option
  • func WithTTLPacket(val time.Duration) Option
  • func WithWhiteListIPs(IPs ...net.IP) Option
  • func WithWriteTimeout(val time.Duration) Option
• type Rules
• type Server
  • func New(opts ...Option) *Server
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Shutdown() error
• type Store

Variables

var NopLogger *nopLogger

Silent logger, produces no output

Functions

func RemoteAddressFromContext

func RemoteAddressFromContext(ctx context.Context) (net.Addr, bool)

func UsernameFromContext

func UsernameFromContext(ctx context.Context) (string, bool)

Types

type Command

type Command int

const (
	Connect Command = iota + 1
	Bind
	UDPAssociate
)

type Driver

type Driver interface {
	Listen(network, address string) (net.Listener, error)
	ListenPacket(network, address string) (net.PacketConn, error)
	Dial(network, address string) (net.Conn, error)
	Resolve(network, address string) (net.Addr, error)
}

type Logger

type Logger interface {
	Info(ctx context.Context, msg string, args ...any)
	Warn(ctx context.Context, msg string, args ...any)
	Error(ctx context.Context, msg string, args ...any)
}

type Metrics

type Metrics interface {
	UploadBytes(ctx context.Context, n int64)
	DownloadBytes(ctx context.Context, n int64)
}

type Option

type Option func(*options)

func WithAllowCommands

func WithAllowCommands(commands ...Command) Option

func WithBlockListHosts

func WithBlockListHosts(hosts ...string) Option

func WithDialTimeout

func WithDialTimeout(val time.Duration) Option

func WithDriver

func WithDriver(val Driver) Option

func WithGetPasswordTimeout

func WithGetPasswordTimeout(val time.Duration) Option

func WithHost

func WithHost(val string) Option

func WithLogger

func WithLogger(val Logger) Option

func WithMaxPacketSize

func WithMaxPacketSize(val int) Option

WithMaxPacketSize sets the maximum size in bytes for the datagram to be read from the socket.

func WithMetrics

func WithMetrics(val Metrics) Option

func WithNatCleanupPeriod

func WithNatCleanupPeriod(val time.Duration) Option

WithNatCleanupPeriod sets the period when the table that links the packets from the sender to the remote host will be cleaned. It makes sense if there's no time limit on the TCP connection. TTL of the packet must be greater than 0.

func WithPacketWriteTimeout

func WithPacketWriteTimeout(val time.Duration) Option

WithPacketWriteTimeout sets the timeout for waiting to write a packet to the remote host.

func WithPasswordAuthentication

func WithPasswordAuthentication() Option

func WithPort

func WithPort(val int) Option

func WithPublicIP

func WithPublicIP(val net.IP) Option

WithPublicIP sets an IP address that is visible on the external Internet, accessible to users outside the local network and will be sent to clients in response to a connection request.

func WithReadTimeout

func WithReadTimeout(val time.Duration) Option

WithReadTimeout sets the read timeout for tcp connection.

func WithRules

func WithRules(val Rules) Option

func WithStaticCredentials

func WithStaticCredentials(val map[string]string) Option

func WithStore

func WithStore(val Store) Option

func WithTTLPacket

func WithTTLPacket(val time.Duration) Option

WithTTLPacket sets how long the packet will stay in the table that links the sender of the packet to the remote host it was meant for. Nat cleanup period must be greater than 0.

func WithWhiteListIPs

func WithWhiteListIPs(IPs ...net.IP) Option

func WithWriteTimeout

func WithWriteTimeout(val time.Duration) Option

WithWriteTimeout sets the write timeout for tcp connection.

type Rules

type Rules interface {
	IsAllowCommand(ctx context.Context, cmd byte) bool
	IsAllowConnection(addr net.Addr) bool
	IsAllowDestination(ctx context.Context, host string) bool
}

type Server

type Server struct {
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Server

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

func (*Server) Shutdown

func (s *Server) Shutdown() error

type Store

type Store interface {
	GetPassword(ctx context.Context, username string) (string, error)
}