socks4

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CmdConnect = 1
	CmdBind    = 2
)

Command codes (CD) for client requests.

View Source 
const (
	DefaultMaxUserIDLen = 256
	DefaultMaxDomainLen = 256
)

Default maximum lengths for SOCKS4a string fields.

View Source 
const (
	RepGranted        = 90
	RepRejected       = 91
	RepIdentFailed    = 92
	RepUserIDMismatch = 93
)

Reply codes (CD) for server responses.

View Source 
const (
	SocksVersion = 4
)

Protocol version.

Variables

View Source 
var (
	ErrInvalidResponseVersion = errors.New("invalid SOCKS4 reply version (must be 0x00)")
	ErrInvalidResponseCode    = errors.New("invalid SOCKS4 reply code")
)

SOCKS4 reply error codes and helpers.

View Source 
var (
	ErrInvalidVersion = errors.New("invalid SOCKS version (must be 4)")
	ErrInvalidCommand = errors.New("invalid command (must be 1=CONNECT or 2=BIND)")
	ErrInvalidIP      = errors.New("invalid IP (must be IPv4)")
	ErrInvalidDomain  = errors.New("invalid SOCKS4a domain usage")
)

Functions

func BaseOnBind 

func BaseOnBind(ctx context.Context, conn net.Conn, req *Request, acceptTimeout, connTimeout time.Duration, bufferSize int) error

BaseOnBind provides BIND implementation

func BaseOnConnect 

func BaseOnConnect(ctx context.Context, conn net.Conn, req *Request, dialer socksnet.Dialer, connTimeout time.Duration, bufferSize int) error

BaseOnConnect provides CONNECT implementation

func BaseOnRequest 

func BaseOnRequest(ctx context.Context, handler ServerHandler, conn net.Conn, req *Request) error

BaseOnRequest provides request handling logic for both CONNECT and BIND commands.

func ListenAndServe 

func ListenAndServe(ctx context.Context, network, address string, handler ServerHandler) error

ListenAndServe listens on the network address and serves SOCKS4 requests.

func Serve 

func Serve(ctx context.Context, listener net.Listener, handler ServerHandler) error

Serve accepts incoming connections on the listener and serves SOCKS4 requests.

func ServeConn 

func ServeConn(ctx context.Context, handler ServerHandler, conn net.Conn) error

ServeConn handles a single client connection, including reading the request and processing it.

func WriteRejectReply 

func WriteRejectReply(conn net.Conn, code byte)

WriteRejectReply sends a SOCKS4 reply with the given rejection code.

func WriteSuccessReply 

func WriteSuccessReply(conn net.Conn, addr net.Addr) error

WriteSuccessReply writes a SOCKS4 success reply with the given network address.

Types

type BaseServerHandler 

type BaseServerHandler struct {
	Dialer             socksnet.Dialer
	RequestTimeout     time.Duration
	BindAcceptTimeout  time.Duration
	BindConnTimeout    time.Duration
	ConnectConnTimeout time.Duration
	ConnectBufferSize  int
	AllowConnect       bool
	AllowBind          bool

	// UserIDChecker is a function that validates the user ID from the SOCKS4 request.
	// It should return an error if the user ID is not allowed, or nil to accept the request.
	// If nil, all user IDs will be accepted by default.
	UserIDChecker func(ctx context.Context, userID string) error
}

BaseServerHandler provides a basic implementation of ServerHandler with configurable options.

func (*BaseServerHandler) OnAccept 

func (d *BaseServerHandler) OnAccept(ctx context.Context, conn net.Conn) error

func (*BaseServerHandler) OnBind 

func (d *BaseServerHandler) OnBind(ctx context.Context, conn net.Conn, req *Request) error

func (*BaseServerHandler) OnConnect 

func (d *BaseServerHandler) OnConnect(ctx context.Context, conn net.Conn, req *Request) error

func (*BaseServerHandler) OnError 

func (d *BaseServerHandler) OnError(ctx context.Context, conn net.Conn, err error)

func (*BaseServerHandler) OnPanic 

func (d *BaseServerHandler) OnPanic(ctx context.Context, conn net.Conn, r any)

func (*BaseServerHandler) OnRequest 

func (d *BaseServerHandler) OnRequest(ctx context.Context, conn net.Conn, req *Request) error

func (*BaseServerHandler) OnUserID 

func (d *BaseServerHandler) OnUserID(ctx context.Context, conn net.Conn, userID string, hasUserID bool) error

type Dialer 

type Dialer struct {
	ProxyAddr string          // e.g. "127.0.0.1:1080"
	UserID    string          // optional SOCKS4 user ID
	Dialer    socksnet.Dialer // optional underlying dialer (nil=DefaultDialer)
}

Dialer implements a SOCKS4/4a proxy dialer.

func NewDialer 

func NewDialer(proxyAddr, userID string, dialer socksnet.Dialer) *Dialer

NewDialer creates a new SOCKS4 dialer instance.

func (*Dialer) Bind 

func (d *Dialer) Bind(network, address string) (net.Conn, *net.TCPAddr, <-chan error, error)

Bind establishes a passive BIND connection using background context.

func (*Dialer) BindContext 

func (d *Dialer) BindContext(
	ctx context.Context,
	network, address string,
) (net.Conn, *net.TCPAddr, <-chan error, error)

BindContext establishes a passive BIND connection via SOCKS4 proxy (CMD_BIND). It returns the active connection and the proxy’s bind address once ready. BindContext establishes a passive BIND connection via SOCKS4 proxy.

func (*Dialer) Dial 

func (d *Dialer) Dial(network, address string) (net.Conn, error)

Dial establishes a connection via SOCKS4/4a proxy using background context.

func (*Dialer) DialConn 

func (d *Dialer) DialConn(conn net.Conn, network, address string) (net.Conn, error)

DialConn upgrades an existing connection using background context.

func (*Dialer) DialConnContext 

func (d *Dialer) DialConnContext(ctx context.Context, conn net.Conn, network, address string) (net.Conn, error)

DialConnContext upgrades an existing connection via SOCKS4/4a proxy (CONNECT command).

func (*Dialer) DialContext 

func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext establishes a connection via SOCKS4/4a proxy (CONNECT command).

func (*Dialer) ProxyAddress 

func (d *Dialer) ProxyAddress() string

ProxyAddress returns the configured SOCKS4 proxy address.

type Reply 

type Reply struct {
	Version byte    // VN; always 0x00 per SOCKS4 spec
	Code    byte    // CD; reply code (0x5A = granted, 0x5B–0x5D = failure)
	Port    uint16  // DSTPORT; server-assigned or echoed port
	IP      [4]byte // DSTIP; server-assigned or echoed address
}

Reply represents a SOCKS4 or SOCKS4a CONNECT/BIND server reply.

func (*Reply) GetIP 

func (r *Reply) GetIP() net.IP

GetIP returns the IPv4 address as net.IP.

func (*Reply) Init 

func (r *Reply) Init(version, code byte, port uint16, ip net.IP)

Init initializes a SOCKS4 Reply.

func (*Reply) IsGranted 

func (r *Reply) IsGranted() bool

IsGranted reports whether the reply indicates success.

func (*Reply) ReadFrom 

func (r *Reply) ReadFrom(src io.Reader) (int64, error)

ReadFrom reads a SOCKS4 Reply from an io.Reader. Implements io.ReaderFrom.

func (*Reply) String 

func (r *Reply) String() string

String returns a string representation of the SOCKS4 Reply.

func (*Reply) Validate 

func (r *Reply) Validate() error

Validate checks the correctness of the SOCKS4 reply fields.

func (*Reply) WriteTo 

func (r *Reply) WriteTo(dst io.Writer) (int64, error)

WriteTo writes a SOCKS4 Reply to an io.Writer. Implements io.WriterTo.

type Request 

type Request struct {
	Version byte    // VN; SOCKS protocol version (should always be 4)
	Command byte    // CD; command code (1 = CONNECT, 2 = BIND)
	Port    uint16  // DSTPORT; destination port (big-endian)
	IP      [4]byte // DSTIP; destination IPv4 address, or 0.0.0.x for SOCKS4a
	UserID  string  // USERID; null-terminated user identifier
	Domain  string  // DOMAIN; null-terminated domain name (SOCKS4a only)
}

Request represents a SOCKS4 or SOCKS4a CONNECT/BIND request.

func (*Request) Addr 

func (r *Request) Addr() string

Addr returns the destination address in "host:port" format.

func (*Request) Host 

func (r *Request) Host() string

Host returns the destination host.

func (*Request) IPv4 

func (r *Request) IPv4() net.IP

IPv4 returns the destination IPv4 address.

func (*Request) Init 

func (r *Request) Init(
	version byte,
	command byte,
	port uint16,
	ip net.IP,
	userID string,
	domain string,
)

Init initializes a SOCKS4 or SOCKS4a CONNECT/BIND request.

func (*Request) IsSOCKS4 

func (r *Request) IsSOCKS4() bool

IsSOCKS4 returns true if the request is a SOCKS4 request.

func (*Request) IsSOCKS4a 

func (r *Request) IsSOCKS4a() bool

IsSOCKS4a returns true if the request is a SOCKS4a request.

func (*Request) ReadFrom 

func (r *Request) ReadFrom(src io.Reader) (int64, error)

ReadFrom reads a SOCKS4 or SOCKS4a CONNECT/BIND request from a Reader. Implements the io.ReaderFrom interface.

func (*Request) ReadFromWithLimits 

func (r *Request) ReadFromWithLimits(src io.Reader, maxUserIDLen, maxDomainLen int64) (int64, error)

ReadFromWithLimits reads a 8-byte SOCKS4 or SOCKS4a CONNECT/BIND request from a Reader. Note that the limits do not include the null-terminator.

func (*Request) ReadHeaderFrom 

func (r *Request) ReadHeaderFrom(src io.Reader) (int64, error)

ReadHeaderFrom reads a 8-byte SOCKS4 or SOCKS4a CONNECT/BIND request from a Reader.

func (*Request) ReadUserIDAndDomain 

func (r *Request) ReadUserIDAndDomain(src io.Reader, maxUserIDLen, maxDomainLen int64) (int64, error)

ReadUserIDAndDomain reads a 8-byte SOCKS4 or SOCKS4a CONNECT/BIND request from a Reader. Note that the limits do not include the null-terminator. Beware if there is data beyond request it can be dropped.

func (*Request) String 

func (r *Request) String() string

String returns a string representation of the SOCKS4(a) Request.

func (*Request) Validate 

func (r *Request) Validate() error

Validate validates a SOCKS4 or SOCKS4a CONNECT/BIND request.

func (*Request) ValidateDomain 

func (r *Request) ValidateDomain() error

Validate validates a SOCKS4 or SOCKS4a CONNECT/BIND request (SOCKS4a only).

func (*Request) ValidateHeader 

func (r *Request) ValidateHeader() error

ValidateHeader validates a SOCKS4 or SOCKS4a CONNECT/BIND request header (first 8 bytes).

func (*Request) WriteTo 

func (r *Request) WriteTo(dst io.Writer) (int64, error)

WriteTo writes a SOCKS4 or SOCKS4a CONNECT/BIND request to a Writer. Implements the io.WriterTo interface.

type ServerHandler 

type ServerHandler interface {
	// OnAccept is called for each accepted connection.
	OnAccept(ctx context.Context, conn net.Conn) error

	// OnUserID is called to validate the user ID from the SOCKS4 request.
	OnUserID(ctx context.Context, conn net.Conn, userID string, hasUserID bool) error

	// OnRequest is called for each request.
	OnRequest(ctx context.Context, conn net.Conn, req *Request) error

	// OnConnect is called for each CONNECT request.
	OnConnect(ctx context.Context, conn net.Conn, req *Request) error

	// OnBind is called for each BIND request.
	OnBind(ctx context.Context, conn net.Conn, req *Request) error

	// OnError is called for each connection error.
	OnError(ctx context.Context, conn net.Conn, err error)

	// OnPanic is called when a panic occurs in any handler goroutine.
	OnPanic(ctx context.Context, conn net.Conn, r any)
}

ServerHandler handles SOCKS4 server events. 

var DefaultServerHandler ServerHandler = &BaseServerHandler{
	RequestTimeout:     10 * time.Second,
	BindAcceptTimeout:  10 * time.Second,
	BindConnTimeout:    60 * time.Second,
	ConnectConnTimeout: 60 * time.Second,
	ConnectBufferSize:  1024 * 32,
	AllowConnect:       true,
	AllowBind:          false,
}

DefaultServerHandler is a default implementation used when no custom ServerHandler is provided to Serve or ListenAndServe.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.