socks5

README

SOCKS 5 proxy

Report Bug | Request Feature

Golang package for implementing a SOCKS 5 proxy server.

CONNECT	BIND	ASSOCIATE
✅ - implemented	❌ - not implemented	🛠 - in progress

Installation

go get github.com/JC5LZiy3HVfV5ux/socks5

Getting Started

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

package main

import (
	"log"

	"github.com/JC5LZiy3HVfV5ux/socks5"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	// Options allowed as nil. Example options: 
	// &socks5.Options{
	//     Authentication: true,
	//     ListenAddress:  "0.0.0.0:1080",
	// }
	srv := socks5.New(nil)

	go func() {
		// Default address: 127.0.0.1:1080
		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 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.

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.

Credits

Original gophers design by @Egon Elbre.

Documentation

Index

• Variables
• func RemoteAddressFromContext(ctx context.Context) (string, bool)
• func UsernameFromContext(ctx context.Context, username string) (string, bool)
• type Driver
• type Logger
• type Metrics
• type Options
• type Server
  • func New(opts *Options) *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) (string, bool)

func UsernameFromContext

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

Types

type Driver

type Driver interface {
	Listen() (net.Listener, error)
	Dial(address string) (net.Conn, 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 Options

type Options struct {
	ListenAddress      string            // default: 127.0.0.1:1080
	ReadTimeout        time.Duration     // default: none
	WriteTimeout       time.Duration     // default: none
	DialTimeout        time.Duration     // default: none
	GetPasswordTimeout time.Duration     // default: none
	Authentication     bool              // default: no authentication required
	StaticCredentials  map[string]string // default: root / password
	Logger             Logger            // default: stdoutLogger
	Store              Store             // default: defaultStore
	Driver             Driver            // default: defaultDriver
	Metrics            Metrics           // default: nopMetrics
}

type Server

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

func New

func New(opts *Options) *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)
}