protocol

type Addr ¶

type Addr struct {
	// Type specifies the address format: IP4Addr, IP6Addr, or FQDNAddr.
	// This determines how the Host field should be interpreted.
	Type AddrType

	// Host contains the address data:
	//   - For IP4Addr: 4-byte IPv4 address
	//   - For IP6Addr: 16-byte IPv6 address
	//   - For FQDNAddr: Domain name as a byte slice
	Host []byte

	// Port is the TCP or UDP port number (0-65535).
	Port uint16

	// NetTyp specifies the network type: "tcp" or "udp".
	// Values like "tcp4", "tcp6", "udp4", "udp6" are normalized to "tcp" or "udp".
	// Empty string is treated as "tcp" in most conversions.
	NetTyp string
}

Addr represents a network address in the SOCKS protocol.

Addr is the central type for representing addresses throughout socksgo. It can represent IPv4, IPv6, or domain name addresses with an associated port and network type.

Wire Format ¶

SOCKS5 encodes addresses as:

• ATYP (1 byte): Address type (IP4Addr=0x01, IP6Addr=0x04, FQDNAddr=0x03)
• DST.ADDR (variable): IP address or domain name
• DST.PORT (2 bytes): Port number in big-endian order

Examples ¶

// Create from IP address
addr := protocol.AddrFromIP(net.ParseIP("192.168.1.1"), 8080, "tcp")

// Create from domain name
addr := protocol.AddrFromFQDN("example.com", 443, "tcp")

// Create from host:port string
addr := protocol.AddrFromHostPort("example.com:443", "tcp")

// Convert to net.TCPAddr
tcpAddr := addr.ToTCP()

func AddrFromFQDN(fqdn string, port uint16, net string) Addr

addr := protocol.AddrFromFQDN("example.com", 443, "tcp")
addr := protocol.AddrFromFQDN("example.com:8080", 443, "tcp") // Uses port 8080

func AddrFromFQDNNoDot(fqdn string, port uint16, net string) Addr

// Standard FQDN
addr := protocol.AddrFromFQDNNoDot("example.com", 443, "tcp")

// FQDN with trailing dot (from DNS response)
addr := protocol.AddrFromFQDNNoDot("example.com.", 443, "tcp") // Trims to "example.com"

func AddrFromHostPort(hostport, network string) Addr

addr := protocol.AddrFromHostPort("example.com:443", "tcp")
addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
addr := protocol.AddrFromHostPort("", "tcp6") // Returns [::]:0

func AddrFromIP(ip net.IP, port uint16, net string) Addr

// IPv4
addr := protocol.AddrFromIP(net.ParseIP("192.168.1.1"), 8080, "tcp")

// IPv6
addr := protocol.AddrFromIP(net.ParseIP("2001:db8::1"), 443, "tcp")

func AddrFromNetAddr(addr net.Addr) Addr

tcpAddr := &net.TCPAddr{IP: net.ParseIP("192.168.1.1"), Port: 8080}
addr := protocol.AddrFromNetAddr(tcpAddr)

udpAddr := &net.UDPAddr{IP: net.ParseIP("::1"), Port: 53}
addr := protocol.AddrFromNetAddr(udpAddr)

func AddrFromNetIPAddrPort(addrPort netip.AddrPort, network ...string) Addr

addrPort := netip.MustParseAddrPort("192.168.1.1:8080")
addr := protocol.AddrFromNetIPAddrPort(addrPort)

func AddrFromString(host string, port uint16, network string) Addr

// IP address
addr := protocol.AddrFromString("192.168.1.1", 8080, "tcp") // Type: IP4Addr
addr := protocol.AddrFromString("::1", 80, "tcp")           // Type: IP6Addr

// Domain name
addr := protocol.AddrFromString("example.com", 443, "tcp") // Type: FQDNAddr

func AddrFromTCPAddr(t *net.TCPAddr) Addr

tcpAddr := &net.TCPAddr{IP: net.ParseIP("192.168.1.1"), Port: 8080}
addr := protocol.AddrFromTCPAddr(tcpAddr)

func AddrFromUDPAddr(u *net.UDPAddr) Addr

udpAddr := &net.UDPAddr{IP: net.ParseIP("8.8.8.8"), Port: 53}
addr := protocol.AddrFromUDPAddr(udpAddr)

func ReadSocks5AssocUDPPacket(
	pool bufpool.Pool,
	conn net.PacketConn,
	p []byte,
	skipAddr bool,
	checkAddr net.Addr,
) (n int, addr Addr, incAddr net.Addr, err error)

func ReadSocks5TunUDPPacket(
	pool bufpool.Pool,
	conn net.Conn,
	p []byte,
	skipAddr bool,
) (n int, addr Addr, err error)

func (a Addr) Copy() Addr

original := protocol.AddrFromHostPort("example.com:443", "tcp")
copy := original.Copy()
// Modifying original won't affect copy

func (a Addr) IpNetwork() string

func (a Addr) IsUnspecified() bool

addr := protocol.AddrFromHostPort("0.0.0.0:0", "tcp")
addr.IsUnspecified() // true

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
addr.IsUnspecified() // false

func (a Addr) Len() int

func (a Addr) Network() string

func (a Addr) PortStr() string

addr := protocol.AddrFromHostPort("example.com:8080", "tcp")
port := addr.PortStr() // Returns "8080"

func (a Addr) ResolveToIP4(
	ctx context.Context,
	lookup func(context.Context, string, string) ([]net.IP, error),
) *Addr

addr := protocol.AddrFromFQDN("example.com", 443, "tcp")
resolved := addr.ResolveToIP4(ctx, net.DefaultResolver.LookupIP)
if resolved != nil {
    // resolved is now an IPv4 address
}

func (a Addr) String() string

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
s := addr.String() // Returns "192.168.1.1:8080"

addr := protocol.AddrFromHostPort("example.com:0", "tcp")
s := addr.String() // Returns "example.com"

func (a Addr) ToFQDN() string

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
host := addr.ToFQDN() // Returns "192.168.1.1"

addr := protocol.AddrFromFQDN("example.com", 443, "tcp")
host := addr.ToFQDN() // Returns "example.com"

func (a Addr) ToHostPort() string

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
hostPort := addr.ToHostPort() // Returns "192.168.1.1:8080"

addr := protocol.AddrFromHostPort("::1:443", "tcp")
hostPort := addr.ToHostPort() // Returns "[::1]:443"

func (a Addr) ToIP() net.IP

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
ip := addr.ToIP() // Returns net.IP{192, 168, 1, 1}

addr := protocol.AddrFromFQDN("example.com", 443, "tcp")
ip := addr.ToIP() // Returns nil

func (a Addr) ToTCP() *net.TCPAddr

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
tcpAddr := addr.ToTCP() // Returns &net.TCPAddr{IP: ..., Port: 8080}

func (a Addr) ToUDP() *net.UDPAddr

addr := protocol.AddrFromHostPort("8.8.8.8:53", "udp")
udpAddr := addr.ToUDP() // Returns &net.UDPAddr{IP: ..., Port: 53}

func (a Addr) ToUnspecified() Addr

func (a Addr) WithDefaultAddr(def *Addr) Addr

defaultAddr := protocol.AddrFromHostPort("127.0.0.1:0", "tcp")

addr := protocol.AddrFromHostPort("0.0.0.0:0", "tcp")
addr = addr.WithDefaultAddr(&defaultAddr) // Returns 127.0.0.1:0

addr = protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
addr = addr.WithDefaultAddr(&defaultAddr) // Returns 192.168.1.1:8080 (unchanged)

func (a Addr) WithDefaultHost(host string) Addr

// Unspecified address with custom host
addr := protocol.AddrFromHostPort("0.0.0.0:0", "tcp")
addr = addr.WithDefaultHost("127.0.0.1") // Returns 127.0.0.1:0

// Unspecified address with empty host (uses 0.0.0.0)
addr := protocol.AddrFromHostPort("0.0.0.0:8080", "tcp")
addr = addr.WithDefaultHost("") // Returns 0.0.0.0:8080

// Already specified - unchanged
addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp")
addr = addr.WithDefaultHost("127.0.0.1") // Returns 192.168.1.1:8080

func (a Addr) WithNetTyp(nt string) Addr

addr := protocol.AddrFromHostPort("192.168.1.1:8080", "tcp4")
addr = addr.WithNetTyp("tcp4") // NetTyp becomes "tcp"

addr := protocol.AddrFromHostPort("8.8.8.8:53", "udp")
addr = addr.WithNetTyp("udp4") // NetTyp becomes "udp"

type AddrType ¶

type AddrType uint8

AddrType represents the type of address in the SOCKS protocol.

AddrType is used to encode/decode addresses in SOCKS requests and replies. The type determines how the Host field in Addr should be interpreted:

• IP4Addr: Host contains 4-byte IPv4 address
• IP6Addr: Host contains 16-byte IPv6 address
• FQDNAddr: Host contains domain name string

const (
	// IP4Addr indicates an IPv4 address (4 bytes).
	// Wire value: 0x01
	IP4Addr AddrType = 0x01

	// IP6Addr indicates an IPv6 address (16 bytes).
	// Wire value: 0x04
	IP6Addr AddrType = 0x04

	// FQDNAddr indicates a fully qualified domain name.
	// Wire value: 0x03
	// The domain name is preceded by a single byte length field.
	FQDNAddr AddrType = 0x03
)

func (a AddrType) String() string

type AuthHandler ¶

type AuthHandler interface {
	Name() string

	// AuthHandlers with Code() == 0x0 or Code() == 0xff are invalid
	Code() AuthMethodCode

	HandleAuth(conn net.Conn, pool bufpool.Pool) (net.Conn, AuthInfo, error)
}

AuthHandler is the server-side authentication interface.

AuthHandler implementations handle the server side of SOCKS5 authentication protocols. Each method (NoAuth, PassAuth, GSSAuth) has its own handler implementation.

Implementation Requirements ¶

• Code() must return a valid method code (not 0x00 or 0xFF)
• HandleAuth() performs the authentication handshake
• Name() returns a human-readable description

Usage ¶

handlers := (&protocol.AuthHandlers{}).Add(&protocol.PassAuthHandler{
    Verify: func(user, pass string) bool {
        return user == "admin" && pass == "secret"
    },
})
conn, info, err := protocol.HandleAuth(conn, pool, handlers)

type AuthHandlers ¶

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

AuthHandlers is a server-side collection of authentication handlers.

AuthHandlers manages a set of authentication handlers that the server supports. When a client proposes authentication methods, the server selects the first matching handler from this collection.

Default Behavior ¶

For nil or empty AuthHandlers:

• Get(NoAuthCode) returns a blank NoAuthHandler
• Get(PassAuthCode) returns a PassAuthHandler that accepts any credentials

Thread Safety ¶

AuthHandlers is not thread-safe. Build the handler list before calling HandleAuth.

Usage ¶

handlers := (&protocol.AuthHandlers{}).
    Add(&protocol.NoAuthHandler{}).
    Add(&protocol.PassAuthHandler{
        Verify: func(user, pass string) bool {
            return isValid(user, pass)
        },
    })

conn, info, err := protocol.HandleAuth(conn, pool, handlers)

func (m *AuthHandlers) Add(handler AuthHandler) *AuthHandlers

func (m *AuthHandlers) CheckSocks4User(user string) (accept bool)

func (m *AuthHandlers) Get(code AuthMethodCode) AuthHandler

type AuthInfo ¶

type AuthInfo struct {
	Code AuthMethodCode
	Name string // May be ""; Use GetName()
	Info map[string]any
}

AuthInfo provides information about a successful authentication.

AuthInfo is returned after successful authentication and contains details about the method used and any relevant credentials or session information.

Fields ¶

• Code: The authentication method code used
• Name: Human-readable method name (may be empty, use GetName())
• Info: Method-specific information (e.g., username for PassAuth)

Examples ¶

// After authentication
info, err := protocol.RunAuth(conn, pool, methods)
if err == nil {
    fmt.Printf("Authenticated with: %s\n", info.GetName())
    if user, ok := protocol.GetAuthParam[string](info, "user"); ok {
        fmt.Printf("User: %s\n", user)
    }
}

func HandleAuth(
	conn net.Conn, pool bufpool.Pool, handlers *AuthHandlers,
) (c net.Conn, i AuthInfo, err error)

func RunAuth(
	conn net.Conn, pool bufpool.Pool, methods *AuthMethods,
) (c net.Conn, i AuthInfo, err error)

func (a AuthInfo) GetName() string

func (a AuthInfo) String() string

type AuthMethod ¶

type AuthMethod interface {
	Name() string

	// AuthMethods with Code() == 0x0 or Code() == 0xff are invalid
	Code() AuthMethodCode

	RunAuth(conn net.Conn, pool bufpool.Pool) (net.Conn, AuthInfo, error)
}

AuthMethod is the client-side authentication interface.

AuthMethod implementations handle the client side of SOCKS5 authentication protocols. Each method (NoAuth, PassAuth, GSSAuth) has its own implementation.

Implementation Requirements ¶

• Code() must return a valid method code (not 0x00 or 0xFF)
• RunAuth() performs the authentication handshake
• Name() returns a human-readable description

Usage ¶

methods := (&protocol.AuthMethods{}).Add(&protocol.PassAuthMethod{
    User: "username",
    Pass: "password",
})
conn, info, err := protocol.RunAuth(conn, pool, methods)

type AuthMethodCode ¶

type AuthMethodCode uint8

AuthMethodCode represents a SOCKS5 authentication method identifier.

AuthMethodCode is used in the authentication negotiation phase to advertise supported methods (client) or select a method (server).

Standard Values ¶

• 0x00: No authentication required
• 0x01: GSS-API
• 0x02: Username/Password
• 0x03-0x7F: IANA assigned
• 0x80-0xFE: Private methods
• 0xFF: No acceptable methods

Examples ¶

code := protocol.PassAuthCode
if code == protocol.PassAuthCode {
    // Handle username/password auth
}

// String representation
code.String() // Returns "user-pass auth"

const (
	// NoAuthCode indicates no authentication is required.
	// Wire value: 0x00
	NoAuthCode AuthMethodCode = 0x0

	// GSSAuthCode indicates GSS-API authentication.
	// Wire value: 0x01
	GSSAuthCode AuthMethodCode = 0x1

	// PassAuthCode indicates username/password authentication.
	// Wire value: 0x02
	PassAuthCode AuthMethodCode = 0x02

	// NoAccAuthCode indicates no acceptable authentication methods.
	// Used by server to reject all client-proposed methods.
	// Wire value: 0xFF
	NoAccAuthCode AuthMethodCode = 0xff
)

func (a AuthMethodCode) String() string

type AuthMethods ¶

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

AuthMethods is a client-side collection of authentication methods.

AuthMethods manages a set of authentication methods that the client is willing to use. Methods are advertised to the server during negotiation, and the selected method is used for authentication.

Thread Safety ¶

AuthMethods is not thread-safe. Build the method list before calling RunAuth.

Usage ¶

methods := (&protocol.AuthMethods{}).
    Add(&protocol.PassAuthMethod{User: "user", Pass: "pass"}).
    Add(&protocol.GSSAuthMethod{Client: gssClient})

conn, info, err := protocol.RunAuth(conn, pool, methods)

func (m *AuthMethods) Add(method AuthMethod) *AuthMethods

func (m *AuthMethods) Clone() *AuthMethods

func (m *AuthMethods) Get(code AuthMethodCode) AuthMethod

func (m *AuthMethods) GetMsg() []byte

func (m *AuthMethods) Rebuild()

func (m *AuthMethods) User() string

type Cmd ¶

type Cmd uint8

Cmd represents a SOCKS command code.

Cmd is used in SOCKS requests to specify the operation the client wants the server to perform. Standard commands are defined in RFC 1928, while extension commands are defined by Tor and Gost projects.

Examples ¶

// Check command type
if cmd == protocol.CmdConnect {
    // Handle CONNECT command
}

// String representation
cmd.String() // Returns "cmd connect"

const (
	// CmdConnect establishes a TCP connection to the target address.
	// Standard SOCKS command (RFC 1928).
	// Wire value: 0x01
	CmdConnect Cmd = 0x01

	// CmdBind listens for incoming connections on the server.
	// Standard SOCKS command (RFC 1928).
	// Used for protocols that require reverse connections (e.g., FTP passive mode).
	// Wire value: 0x02
	CmdBind Cmd = 0x02

	// CmdUDPAssoc associates a UDP port for UDP relay.
	// Standard SOCKS command (RFC 1928).
	// Returns a UDP socket address for sending/receiving UDP packets.
	// Wire value: 0x03
	CmdUDPAssoc Cmd = 0x03

	// CmdTorResolve performs a forward DNS lookup (Tor extension).
	// https://spec.torproject.org/socks-extensions.html
	// Wire value: 0xF0
	CmdTorResolve Cmd = 0xF0

	// CmdTorResolvePtr performs a reverse DNS lookup (Tor extension).
	// https://spec.torproject.org/socks-extensions.html
	// Wire value: 0xF1
	CmdTorResolvePtr Cmd = 0xF1

	// CmdGostMuxBind creates a multiplexed bind using smux (Gost extension).
	// Allows multiple incoming connections over a single TCP connection.
	// Wire value: 0xF2
	CmdGostMuxBind Cmd = 0xF2

	// CmdGostUDPTun tunnels UDP over TCP (Gost extension).
	// Encapsulates UDP packets in a TCP connection.
	// Wire value: 0xF3
	CmdGostUDPTun Cmd = 0xF3
)

func (cmd Cmd) String() string

type GSSAPIClient ¶

type GSSAPIClient interface {
	// InitSecContext produces a context token to send to the server.
	// `token` is the input from the peer (nil on first call).
	// Returns outputToken (to send), needContinue=true if more tokens are needed, or err.
	InitSecContext(
		targetName string,
		token []byte,
	) (outputToken []byte, needContinue bool, err error)

	// DeleteSecContext cleans up the context when done.
	DeleteSecContext() error
}

GSSAPIClient is the interface for client-side GSS-API implementations.

This interface should be implemented by a GSS-API library wrapper (e.g., MIT Kerberos, Heimdal).

Methods ¶

• InitSecContext: Initialize security context and produce tokens
• DeleteSecContext: Clean up context resources

Implementation Notes ¶

The implementation should: 1. On first call with nil token, initiate GSS context 2. Process server tokens and produce response tokens 3. Return needContinue=false when GSS_S_COMPLETE is reached 4. Handle context cleanup in DeleteSecContext

type GSSAPIServer ¶

type GSSAPIServer interface {
	// AcceptSecContext processes a token from the client, returning a token to send back.
	// Returns outputToken, the authenticated principal (srcName), needContinue flag, or err.
	AcceptSecContext(
		token []byte,
	) (outputToken []byte, srcName string, needContinue bool, err error)

	// DeleteSecContext cleans up the context when done.
	DeleteSecContext() error
}

GSSAPIServer is the interface for server-side GSS-API implementations.

This interface should be implemented by a GSS-API library wrapper (e.g., MIT Kerberos, Heimdal) for server-side authentication.

Methods ¶

• AcceptSecContext: Process client tokens and produce response tokens
• DeleteSecContext: Clean up context resources

Implementation Notes ¶

The implementation should: 1. Process client tokens through AcceptSecContext 2. Return the authenticated principal name (srcName) on success 3. Return needContinue=false when GSS_S_COMPLETE is reached 4. Handle context cleanup in DeleteSecContext

type GSSAuthHandler ¶

type GSSAuthHandler struct {
	Server GSSAPIServer // Provided GSS implementation
}

GSSAuthHandler implements server-side GSS-API authentication.

GSSAuthHandler wraps a GSSAPIServer implementation to provide SOCKS5 GSS-API authentication. It handles token framing and exchange.

Fields ¶

• Server: GSS-API server implementation (required)

Status ¶

This is a STUB implementation. It provides the framework but requires an external GSS-API library to function.

Examples ¶

// Requires a GSS-API implementation
gssServer := &myGSS.Server{Keytab: "/etc/krb5.keytab"}
handler := &protocol.GSSAuthHandler{Server: gssServer}
handlers := (&protocol.AuthHandlers{}).Add(handler)

func (h *GSSAuthHandler) Code() AuthMethodCode

func (h *GSSAuthHandler) HandleAuth(
	conn net.Conn,
	pool bufpool.Pool,
) (net.Conn, AuthInfo, error)

func (h *GSSAuthHandler) Name() string

type GSSAuthMethod ¶

type GSSAuthMethod struct {
	Client     GSSAPIClient // Provided GSS implementation
	TargetName string       // e.g. "socks@server.example.com"
}

GSSAuthMethod implements client-side GSS-API authentication.

GSSAuthMethod wraps a GSSAPIClient implementation to provide SOCKS5 GSS-API authentication. It handles token framing and exchange.

Fields ¶

• Client: GSS-API client implementation (required)
• TargetName: Service principal name (e.g., "socks@proxy.example.com")

Status ¶

This is a STUB implementation. It provides the framework but requires an external GSS-API library to function.

Examples ¶

// Requires a GSS-API implementation
gssClient := &myGSS.Client{ServiceName: "socks@proxy.example.com"}
method := &protocol.GSSAuthMethod{
    Client: gssClient,
    TargetName: "socks@proxy.example.com",
}
methods := (&protocol.AuthMethods{}).Add(method)

func (m *GSSAuthMethod) Code() AuthMethodCode

func (m *GSSAuthMethod) Name() string

func (m *GSSAuthMethod) RunAuth(
	conn net.Conn,
	pool bufpool.Pool,
) (net.Conn, AuthInfo, error)

type NoAuthHandler ¶

type NoAuthHandler struct{}

NoAuthHandler implements server-side no-authentication.

This handler accepts any connection without requiring credentials. It's the simplest auth handler and is commonly used for open proxies.

Wire Format ¶

Server response (2 bytes):

• VER: 0x05
• METHOD: 0x00 (NoAuth)

Examples ¶

handlers := (&protocol.AuthHandlers{}).Add(&protocol.NoAuthHandler{})

func (m *NoAuthHandler) Code() AuthMethodCode

func (m *NoAuthHandler) HandleAuth(
	conn net.Conn,
	pool bufpool.Pool,
) (net.Conn, AuthInfo, error)

func (m *NoAuthHandler) Name() string

type PassAuthHandler ¶

type PassAuthHandler struct {
	// Nil means any user+pass combination is allowed
	VerifyFn func(user, pass string) bool
}

PassAuthHandler implements server-side username/password authentication.

PassAuthHandler validates client credentials using the provided VerifyFn function. If VerifyFn is nil, all credentials are accepted (useful for testing or open proxies).

Fields ¶

• VerifyFn: Validation function. Returns true for valid credentials. If nil, all credentials are accepted.

Wire Format ¶

See PassAuthMethod for the complete protocol description.

Examples ¶

// Strict validation
handler := &protocol.PassAuthHandler{
    Verify: func(user, pass string) bool {
        return user == "admin" && pass == "secret"
    },
}

// Accept all credentials
handler := &protocol.PassAuthHandler{}

handlers := (&protocol.AuthHandlers{}).Add(handler)
conn, info, err := protocol.HandleAuth(conn, pool, handlers)

func (m *PassAuthHandler) Code() AuthMethodCode

func (m *PassAuthHandler) HandleAuth(
	conn net.Conn,
	pool bufpool.Pool,
) (net.Conn, AuthInfo, error)

func (m *PassAuthHandler) Name() string

type PassAuthMethod ¶

type PassAuthMethod struct {
	User, Pass string
}

PassAuthMethod implements client-side username/password authentication.

PassAuthMethod sends credentials to the server using the RFC 1929 protocol. The username and password are sent in plain text.

Fields ¶

• User: Username (1-255 bytes)
• Pass: Password (1-255 bytes)

Wire Format ¶

Client request:

• VER (1 byte): 0x01
• ULEN (1 byte): Username length
• UNAME (variable): Username
• PLEN (1 byte): Password length
• PASSWD (variable): Password

Server response:

• VER (1 byte): 0x01
• STATUS (1 byte): 0x00=success, 0x01=failure

Examples ¶

method := &protocol.PassAuthMethod{
    User: "admin",
    Pass: "secret",
}
methods := (&protocol.AuthMethods{}).Add(method)
conn, info, err := protocol.RunAuth(conn, pool, methods)

func (m *PassAuthMethod) Code() AuthMethodCode

func (m *PassAuthMethod) Name() string

func (m *PassAuthMethod) RunAuth(
	conn net.Conn,
	pool bufpool.Pool,
) (net.Conn, AuthInfo, error)

type ReplyStatus ¶

type ReplyStatus uint8

ReplyStatus represents a SOCKS reply status code.

ReplyStatus is used in SOCKS replies to indicate the result of a request. SOCKS4 and SOCKS5 use different status code ranges, and this type provides methods to convert between them (To4, To5).

Examples ¶

// Check if request succeeded
if status.Ok() {
    // Request granted
}

// Convert to SOCKS4 status
status4 := status.To4()

// String representation
status.String() // Returns "succeeded", "host unreachable", etc.

const (
	// SuccReply indicates the request succeeded.
	// Wire value: 0x0
	SuccReply ReplyStatus = 0x0

	// FailReply indicates a general SOCKS server failure.
	// Wire value: 0x1
	FailReply ReplyStatus = 0x1

	// DisallowReply indicates the connection was not allowed by ruleset.
	// Typically used when address filters reject the request.
	// Wire value: 0x2
	DisallowReply ReplyStatus = 0x2

	// NetUnreachReply indicates the network is unreachable.
	// Wire value: 0x3
	NetUnreachReply ReplyStatus = 0x3

	// HostUnreachReply indicates the host is unreachable.
	// Typically used when dialing the target fails.
	// Wire value: 0x4
	HostUnreachReply ReplyStatus = 0x4

	// ConnRefusedReply indicates the connection was refused by the target.
	// Wire value: 0x5
	ConnRefusedReply ReplyStatus = 0x5

	// TTLExpiredReply indicates the TTL expired (used in UDP assoc).
	// Wire value: 0x6
	TTLExpiredReply ReplyStatus = 0x6

	// CmdNotSuppReply indicates the command is not supported.
	// Wire value: 0x7
	CmdNotSuppReply ReplyStatus = 0x7

	// AddrNotSuppReply indicates the address type is not supported.
	// Wire value: 0x8
	AddrNotSuppReply ReplyStatus = 0x80
)

const (
	// Granted indicates the request was granted.
	// Wire value: 90
	Granted ReplyStatus = 90

	// Rejected indicates the request was rejected or failed.
	// Wire value: 91
	Rejected ReplyStatus = 91

	// IdentRequired indicates the client program and identd report
	// different user-ids.
	// Wire value: 92
	IdentRequired ReplyStatus = 92

	// IdentFailed indicates the socks server cannot connect to identd
	// on the client.
	// Wire value: 93
	IdentFailed ReplyStatus = 93
)

const (
	// TorDescNotFound indicates the onion service descriptor cannot be found.
	// Wire value: 0xf0
	TorDescNotFound ReplyStatus = 0xf0

	// TorDescInvalid indicates the onion service descriptor is invalid.
	// Wire value: 0xf1
	TorDescInvalid ReplyStatus = 0xf1

	// TorIntroFail indicates the onion service introduction failed.
	// Wire value: 0xf2
	TorIntroFail ReplyStatus = 0xf2

	// TorRendFailed indicates the onion service rendezvous failed.
	// Wire value: 0xf3
	TorRendFailed ReplyStatus = 0xf3

	// TorMissAuth indicates the onion service is missing client authorization.
	// Wire value: 0xf4
	TorMissAuth ReplyStatus = 0xf4

	// TorWrongAuth indicates the onion service has wrong client authorization.
	// Wire value: 0xf5
	TorWrongAuth ReplyStatus = 0xf5

	// TorInvalidAddr indicates an invalid onion service address.
	// Wire value: 0xf6
	TorInvalidAddr ReplyStatus = 0xf6

	// TorIntroTimeOut indicates the onion service introduction timed out.
	// Wire value: 0xf7
	TorIntroTimeOut ReplyStatus = 0xf7
)

func (r ReplyStatus) Ok() bool

func (r ReplyStatus) String() string

protocol.SuccReply.String()        // "succeeded"
protocol.HostUnreachReply.String() // "host unreachable"
protocol.Granted.String()          // "request granted"

func (r ReplyStatus) To4() ReplyStatus

func (r ReplyStatus) To5() ReplyStatus

type Socks5UDPClient ¶

type Socks5UDPClient interface {
	gonnect.UDPConn

	WriteToIpPort(p []byte, ip net.IP, port uint16) (n int, err error)

	ReadFromUDP(b []byte) (n int, addr *net.UDPAddr, err error)
	WriteToUDP(b []byte, addr *net.UDPAddr) (int, error)

	ReadFromUDPAddrPort(b []byte) (n int, addr netip.AddrPort, err error)
	WriteToUDPAddrPort(b []byte, addr netip.AddrPort) (int, error)

	ReadMsgUDP(b, oob []byte) (n, oobn, flags int,
		addr *net.UDPAddr, err error)
	ReadMsgUDPAddrPort(b, oob []byte) (n, oobn, flags int,
		addr netip.AddrPort, err error)
	WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, err error)
	WriteMsgUDPAddrPort(b, oob []byte, addr netip.AddrPort) (n, oobn int,
		err error)
}

Socks5UDPClient is the interface for SOCKS5 UDP clients.

This interface combines net.Conn and net.PacketConn to support both stream-oriented and packet-oriented operations. It's implemented by:

• Socks5UDPClientAssoc: Standard UDP ASSOC
• Socks5UDPClientTUN: Gost UDP Tunnel

Methods ¶

• Read/Write: Stream-oriented I/O (uses default remote address)
• ReadFrom/WriteTo: Packet-oriented I/O with explicit addresses
• ReadFromUDP/WriteToUDP: UDP-specific packet I/O
• ReadFromUDPAddrPort/WriteToUDPAddrPort: AddrPort-based I/O
• ReadMsgUDP/WriteMsgUDP: UDP messages with out-of-band data
• WriteToIpPort: Write to a specific IP and port

type Socks5UDPClientAssoc ¶

type Socks5UDPClientAssoc struct {
	gonnect.PacketConn
	DefaultHeader []byte // For binded UDP connections (ones with fixed raddr)
	Pool          bufpool.Pool
	Raddr         net.Addr
	OnClose       func()
}

Socks5UDPClientAssoc implements standard SOCKS5 UDP ASSOCIATE.

This type wraps a UDP PacketConn to provide SOCKS5 UDP relay functionality. It adds SOCKS5 UDP headers to outgoing packets and parses them from incoming packets.

Usage ¶

After a successful UDP ASSOCIATE command over TCP, use the returned server UDP address to create this client:

udpConn, _ := net.DialUDP("udp", nil, serverUDPAddr)
client := protocol.NewSocks5UDPClientAssoc(udpConn, &bindAddr, pool, onClose)
defer client.Close()

// Send UDP packet
client.WriteToUDP(data, &net.UDPAddr{IP: targetIP, Port: targetPort})

// Receive UDP packet
n, addr, err := client.ReadFromUDP(buf)

func NewSocks5UDPClientAssoc(
	conn gonnect.PacketConn, addr *Addr, pool bufpool.Pool, onc func(),
) *Socks5UDPClientAssoc

func (uc *Socks5UDPClientAssoc) Close() error

func (uc *Socks5UDPClientAssoc) Read(b []byte) (n int, err error)

func (uc *Socks5UDPClientAssoc) ReadFrom(
	p []byte,
) (n int, addr net.Addr, err error)

func (uc *Socks5UDPClientAssoc) ReadFromUDP(
	b []byte,
) (n int, addr *net.UDPAddr, err error)

func (uc *Socks5UDPClientAssoc) ReadFromUDPAddrPort(
	b []byte,
) (n int, addr netip.AddrPort, err error)

func (uc *Socks5UDPClientAssoc) ReadMsgUDP(
	b, oob []byte,
) (n, oobn, flags int, addr *net.UDPAddr, err error)

func (uc *Socks5UDPClientAssoc) ReadMsgUDPAddrPort(
	b, oob []byte,
) (n, oobn, flags int, addr netip.AddrPort, err error)

func (uc *Socks5UDPClientAssoc) RemoteAddr() net.Addr

func (uc *Socks5UDPClientAssoc) Write(b []byte) (n int, err error)

func (uc *Socks5UDPClientAssoc) WriteMsgUDP(
	b, oob []byte,
	addr *net.UDPAddr,
) (n, oobn int, err error)

func (uc *Socks5UDPClientAssoc) WriteMsgUDPAddrPort(
	b, oob []byte,
	addr netip.AddrPort,
) (n, oobn int, err error)

func (uc *Socks5UDPClientAssoc) WriteTo(
	p []byte,
	addr net.Addr,
) (n int, err error)

func (uc *Socks5UDPClientAssoc) WriteToIpPort(
	p []byte,
	ip net.IP,
	port uint16,
) (n int, err error)

func (uc *Socks5UDPClientAssoc) WriteToUDP(
	b []byte,
	addr *net.UDPAddr,
) (int, error)

func (uc *Socks5UDPClientAssoc) WriteToUDPAddrPort(
	b []byte,
	addr netip.AddrPort,
) (int, error)

type Socks5UDPClientTUN ¶

type Socks5UDPClientTUN struct {
	net.Conn
	DefaultHeader []byte // For binded UDP connections (ones with fixed raddr)
	Pool          bufpool.Pool
	Laddr, Raddr  net.Addr
	OnClose       func()
}

Socks5UDPClientTUN implements Gost's UDP Tunnel extension.

This type wraps a TCP Conn to provide UDP-over-TCP relay. Unlike standard UDP ASSOC which uses a separate UDP connection, Gost's tunnel encapsulates UDP packets within a TCP stream.

Wire Format ¶

Each UDP packet is prefixed with a header:

• RSV (2 bytes): Payload length (big-endian)
• FRAG (1 byte): Always 0xFF
• ATYP (1 byte): Address type
• DST.ADDR/DST.PORT: Destination address
• DATA: UDP payload

Usage ¶

After a successful GostUDPTun command over TCP:

client := protocol.NewSocks5UDPClientTUN(tcpConn, bindAddr, &targetAddr, pool)
defer client.Close()

// Send UDP packet (automatically encapsulated in TCP)
client.WriteToUDP(data, &net.UDPAddr{IP: targetIP, Port: targetPort})

// Receive UDP packet
n, addr, err := client.ReadFromUDP(buf)

func NewSocks5UDPClientTUN(
	conn net.Conn, laddr Addr, raddr *Addr, pool bufpool.Pool,
) *Socks5UDPClientTUN

func (uc *Socks5UDPClientTUN) Close() error

func (uc *Socks5UDPClientTUN) LocalAddr() net.Addr

func (uc *Socks5UDPClientTUN) Read(b []byte) (n int, err error)

func (uc *Socks5UDPClientTUN) ReadFrom(
	p []byte,
) (n int, addr net.Addr, err error)

func (uc *Socks5UDPClientTUN) ReadFromUDP(
	b []byte,
) (n int, addr *net.UDPAddr, err error)

func (uc *Socks5UDPClientTUN) ReadFromUDPAddrPort(
	b []byte,
) (n int, addr netip.AddrPort, err error)

func (uc *Socks5UDPClientTUN) ReadMsgUDP(
	b, oob []byte,
) (n, oobn, flags int, addr *net.UDPAddr, err error)

func (uc *Socks5UDPClientTUN) ReadMsgUDPAddrPort(
	b, oob []byte,
) (n, oobn, flags int, addr netip.AddrPort, err error)

func (uc *Socks5UDPClientTUN) RemoteAddr() net.Addr

func (uc *Socks5UDPClientTUN) Write(b []byte) (n int, err error)

func (uc *Socks5UDPClientTUN) WriteMsgUDP(
	b, oob []byte,
	addr *net.UDPAddr,
) (n, oobn int, err error)

func (uc *Socks5UDPClientTUN) WriteMsgUDPAddrPort(
	b, oob []byte,
	addr netip.AddrPort,
) (n, oobn int, err error)

func (uc *Socks5UDPClientTUN) WriteTo(
	p []byte,
	addr net.Addr,
) (n int, err error)

func (uc *Socks5UDPClientTUN) WriteToIpPort(
	p []byte,
	ip net.IP,
	port uint16,
) (n int, err error)

func (uc *Socks5UDPClientTUN) WriteToUDP(
	b []byte,
	addr *net.UDPAddr,
) (int, error)

func (uc *Socks5UDPClientTUN) WriteToUDPAddrPort(
	b []byte,
	addr netip.AddrPort,
) (int, error)

type UnknownAddrTypeError ¶

type UnknownAddrTypeError struct {
	Type AddrType
}

UnknownAddrTypeError is returned when an unknown address type is encountered in a SOCKS request or reply.

func (e UnknownAddrTypeError) Error() string

type UnknownAuthVerError ¶

type UnknownAuthVerError struct {
	Version int
}

UnknownAuthVerError is returned when an unknown authentication version is received during SOCKS5 auth negotiation.

func (e UnknownAuthVerError) Error() string

type UnsupportedAuthMethodError ¶

type UnsupportedAuthMethodError struct {
	Method AuthMethodCode
}

UnsupportedAuthMethodError is returned when the server selects an authentication method that the client doesn't support.

func (e UnsupportedAuthMethodError) Error() string

type Wrong4ReplyVerError ¶

type Wrong4ReplyVerError struct {
	Version int
}

Wrong4ReplyVerError is returned when a SOCKS4 reply has an unexpected version byte.

SOCKS4 replies should always have version byte 0.

func (e Wrong4ReplyVerError) Error() string

type WrongProtocolVerError ¶

type WrongProtocolVerError struct {
	Version int
}

WrongProtocolVerError is returned when a SOCKS request or reply has an unexpected protocol version.

func (e WrongProtocolVerError) Error() string