socks5-protocol

name	socks5-protocol
description	Use when implementing or debugging the SOCKS5 protocol (RFC 1928) in pkg/socks5 — handshakes, auth method negotiation, request parsing, IPv4/IPv6/domain address types, error codes, or byte-level wire-format tests.

SOCKS5 Protocol

Expertise in implementing and debugging the SOCKS5 protocol (RFC 1928): authentication mechanisms, request parsing, and connection handling.

When to use this skill

• Implementing SOCKS5 protocol handlers
• Debugging SOCKS5 connection issues
• Adding authentication to SOCKS5
• Testing SOCKS5 client/server interactions
• Optimizing SOCKS5 performance

Expertise areas

• RFC 1928 SOCKS5 protocol specification
• Authentication mechanisms (no-auth, username/password, GSSAPI)
• Request parsing and validation
• Connection establishment and teardown
• Error handling and protocol compliance
• Performance optimization for concurrent connections
• Testing strategies for SOCKS5

Key files

• pkg/socks5/socks5.go - Main SOCKS5 server implementation
• pkg/socks5/auth.go - Authentication handler
• pkg/socks5/request.go - SOCKS5 request parsing
• pkg/socks5/constants.go - Protocol constants
• pkg/socks5/errors.go - Error types
• pkg/socks5/socks5_test.go - SOCKS5 tests
• pkg/socks5/auth_test.go - Authentication tests
• pkg/socks5/request_test.go - Request parsing tests

Common tasks

Writing a SOCKS5 authentication handler

Reference pkg/socks5/auth.go for the authentication pattern. Support username/password authentication with proper error responses.

Debugging connection issues

Check pkg/socks5/request.go for request parsing. Verify SOCKS version, command type, and address format compliance.

Adding error handling

Use error types from pkg/socks5/errors.go. Always return proper SOCKS5 error codes before closing connection.

Testing SOCKS5

Use the patterns in pkg/socks5/*_test.go files. Test both valid and invalid handshakes, all auth methods, and various request types.

Example patterns

Handling a SOCKS5 greeting

// Read greeting from client
greeting := make([]byte, 2)
_, err := io.ReadFull(conn, greeting)
if err != nil {
    return err
}

// Validate SOCKS version
if greeting[0] != socks5Version {
    return fmt.Errorf("invalid SOCKS version: %d", greeting[0])
}

// Select authentication method
numMethods := greeting[1]
methods := make([]byte, numMethods)
_, err = io.ReadFull(conn, methods)
if err != nil {
    return err
}

Parsing a SOCKS5 request

request := make([]byte, 4)
_, err := io.ReadFull(conn, request)
if err != nil {
    return err
}

cmd := request[1]  // CONNECT, BIND, or UDP
atyp := request[3] // Address type

// Parse address based on type
var addr string
switch atyp {
case ipv4Type:
    // Parse IPv4 address and port
case ipv6Type:
    // Parse IPv6 address and port
case domainType:
    // Parse domain name and port
}

Testing approach

• Test all SOCKS5 commands (CONNECT, BIND, UDP ASSOCIATE)
• Test all authentication methods (NO AUTH, USERNAME/PASSWORD)
• Test various address types (IPv4, IPv6, domain names)
• Test protocol edge cases and malformed requests
• Verify error responses are SOCKS5 compliant
• Check connection cleanup and resource management

Performance considerations

• Use buffered I/O for protocol parsing
• Implement timeouts for each phase
• Monitor goroutine usage for concurrent connections
• Consider connection pooling for destination servers
• Profile authentication overhead

Security considerations

• Validate all input before processing
• Use constant-time comparison for password validation
• Never log passwords or sensitive authentication data
• Implement rate limiting for failed authentication attempts
• Properly close connections on authentication failure

References

• RFC 1928: SOCKS Protocol Version 5
• Existing test cases in pkg/socks5/*_test.go

Related skills

• http-proxy - For comparing proxy protocols
• credential-management - For auth handling
• dns-resolution - For hostname resolution
• go-concurrency - For connection handling