socks5

README

Socks5

Provides the socks5 package that implements a SOCKS5 server. SOCKS (Secure Sockets) is used to route traffic between a client and server through an intermediate proxy layer. This can be used to bypass firewalls or NATs.

Feature

The package has the following features:

• "No Auth" mode
• User/Password authentication
• Support for the CONNECT command
• Support for the ASSOCIATE command
• Rules to do granular filtering of commands
• Custom DNS resolution
• Unit tests

TODO

The package still needs the following:

• Support for the BIND command

Example

Below is a simple example of usage

// Create a SOCKS5 server
conf := &socks5.Config{}
server, err := socks5.New(conf)
if err != nil {
  panic(err)
}

// Create SOCKS5 proxy on localhost port 8000
if err := server.ListenAndServe("tcp", "127.0.0.1:8000"); err != nil {
  panic(err)
}

Documentation

Index

• Constants
• Variables
• type AddrSpec
  • func (a AddrSpec) Address() string
  • func (a *AddrSpec) BinarySize() int
  • func (a *AddrSpec) String() string
  • func (a *AddrSpec) WriteTo(w io.Writer) (int, error)
• type AddressRewriter
• type AuthContext
• type Authenticator
• type Config
• type CredentialStore
• type DNSResolver
  • func (d DNSResolver) Resolve(ctx context.Context, name string) (context.Context, net.IP, error)
• type ErrorLogger
• type NameResolver
• type NoAuthAuthenticator
  • func (a NoAuthAuthenticator) Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)
  • func (a NoAuthAuthenticator) GetCode() uint8
• type PermitCommand
  • func (p *PermitCommand) Allow(ctx context.Context, req *Request) (context.Context, bool)
• type Request
  • func NewRequest(bufConn io.Reader) (*Request, error)
• type RuleSet
  • func PermitAll() RuleSet
  • func PermitNone() RuleSet
• type Server
  • func New(conf *Config) (*Server, error)
  • func (s *Server) ListenAndServe(network, addr string) error
  • func (s *Server) Serve(l net.Listener) error
  • func (s *Server) ServeConn(conn net.Conn) error
• type StaticCredentials
  • func (s StaticCredentials) Valid(user, password string) bool
• type UserPassAuthenticator
  • func (a UserPassAuthenticator) Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)
  • func (a UserPassAuthenticator) GetCode() uint8

Constants

const (
	// AuthMethodNoAuth X'00' NO AUTHENTICATION REQUIRED
	AuthMethodNoAuth = uint8(0)

	// AuthMethodUserPass X'02' USERNAME/PASSWORD
	AuthMethodUserPass = uint8(2)

	// AuthMethodNoAcceptable X'FF' NO ACCEPTABLE METHODS
	AuthMethodNoAcceptable = uint8(255)
)

AuthMethods

const (
	// AuthUserPassVersion the VER field contains the current version
	// of the subnegotiation, which is X'01'
	AuthUserPassVersion = uint8(1)
	// AuthUserPassStatusSuccess a STATUS field of X'00' indicates success
	AuthUserPassStatusSuccess = uint8(0)
	// AuthUserPassStatusFailure if the server returns a `failure'
	// (STATUS value other than X'00') status, it MUST close the connection.
	AuthUserPassStatusFailure = uint8(1)
)

const (
	// CommandConnect CMD CONNECT X'01'
	CommandConnect = uint8(1)
	// CommandBind CMD BIND X'02'. The BIND request is used in protocols
	// which require the client to accept connections from the server.
	CommandBind = uint8(2)
	// CommandAssociate CMD UDP ASSOCIATE X'03'.  The UDP ASSOCIATE request
	// is used to establish an association within the UDP relay process to
	// handle UDP datagrams.
	CommandAssociate = uint8(3)
)

CMD declaration

const (
	// AddressIPv4 IP V4 address: X'01'
	AddressIPv4 = uint8(1)
	// AddressDomainName DOMAINNAME: X'03'
	AddressDomainName = uint8(3)
	// AddressIPv6 IP V6 address: X'04'
	AddressIPv6 = uint8(4)
)

ATYP address type of following address declaration

const (
	// ReplySucceeded X'00' succeeded
	ReplySucceeded uint8 = iota
	// ReplyServerFailure X'01' general SOCKS server failure
	ReplyServerFailure
	// ReplyRuleFailure X'02' connection not allowed by ruleset
	ReplyRuleFailure
	// ReplyNetworkUnreachable X'03' Network unreachable
	ReplyNetworkUnreachable
	// ReplyHostUnreachable X'04' Host unreachable
	ReplyHostUnreachable
	// ReplyConnectionRefused X'05' Connection refused
	ReplyConnectionRefused
	// ReplyTTLExpired X'06' TTL expired
	ReplyTTLExpired
	// ReplyCommandNotSupported X'07' Command not supported
	ReplyCommandNotSupported
	// ReplyAddrTypeNotSupported X'08' Address type not supported
	ReplyAddrTypeNotSupported
)

REP field declaration

Variables

var (
	// ErrUserAuthFailed failed to authenticate
	ErrUserAuthFailed = fmt.Errorf("User authentication failed")
	// ErrNoSupportedAuth authenticate method not supported
	ErrNoSupportedAuth = fmt.Errorf("No supported authentication mechanism")
)

var ErrUDPFragmentNoSupported = errors.New("UDP fragments not supported")

Types

type AddrSpec

type AddrSpec struct {
	FQDN string
	IP   net.IP
	Port int
}

AddrSpec is used to return the target AddrSpec which may be specified as IPv4, IPv6, or a FQDN

func (AddrSpec) Address

func (a AddrSpec) Address() string

Address returns a string suitable to dial; prefer returning IP-based address, fallback to FQDN

func (*AddrSpec) BinarySize

func (a *AddrSpec) BinarySize() int

func (*AddrSpec) String

func (a *AddrSpec) String() string

func (*AddrSpec) WriteTo

func (a *AddrSpec) WriteTo(w io.Writer) (int, error)

type AddressRewriter

type AddressRewriter interface {
	Rewrite(ctx context.Context, request *Request) (context.Context, *AddrSpec)
}

AddressRewriter is used to rewrite a destination transparently

type AuthContext

type AuthContext struct {
	// Provided auth method
	Method uint8
	// Payload provided during negotiation.
	// Keys depend on the used auth method.
	// For UserPassAuth contains Username
	Payload map[string]string
}

AuthContext A Request encapsulates authentication state provided during negotiation

type Authenticator

type Authenticator interface {
	Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)
	GetCode() uint8
}

Authenticator auth

type Config

type Config struct {
	// AuthMethods can be provided to implement custom authentication
	// By default, "auth-less" mode is enabled.
	// For password-based auth use UserPassAuthenticator.
	AuthMethods []Authenticator

	// If provided, username/password authentication is enabled,
	// by appending a UserPassAuthenticator to AuthMethods. If not provided,
	// and AUthMethods is nil, then "auth-less" mode is enabled.
	Credentials CredentialStore

	// Resolver can be provided to do custom name resolution.
	// Defaults to DNSResolver if not provided.
	Resolver NameResolver

	// Rules is provided to enable custom logic around permitting
	// various commands. If not provided, PermitAll is used.
	Rules RuleSet

	// Rewriter can be used to transparently rewrite addresses.
	// This is invoked before the RuleSet is invoked.
	// Defaults to NoRewrite.
	Rewriter AddressRewriter

	// BindIP is used for bind or udp associate
	BindIP net.IP

	// BindIP is used for bind or udp associate
	BindPort int

	// Logger can be used to provide a custom log target.
	// Defaults to stdout.
	Logger ErrorLogger

	// Optional function for dialing out
	Dial func(ctx context.Context, network, addr string) (net.Conn, error)

	ListenPacket func(ctx context.Context, network string) (net.PacketConn, error)
}

Config is used to setup and configure a Server

type CredentialStore

type CredentialStore interface {
	Valid(user, password string) bool
}

CredentialStore is used to support user/pass authentication

type DNSResolver

type DNSResolver struct{}

DNSResolver uses the system DNS to resolve host names

func (DNSResolver) Resolve

func (d DNSResolver) Resolve(ctx context.Context, name string) (context.Context, net.IP, error)

Resolve ...

type ErrorLogger

type ErrorLogger interface {
	Printf(format string, v ...interface{})
}

ErrorLogger error handler, compatible with std logger

type NameResolver

type NameResolver interface {
	Resolve(ctx context.Context, name string) (context.Context, net.IP, error)
}

NameResolver is used to implement custom name resolution

type NoAuthAuthenticator

type NoAuthAuthenticator struct{}

NoAuthAuthenticator is used to handle the "No Authentication" mode

func (NoAuthAuthenticator) Authenticate

func (a NoAuthAuthenticator) Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)

Authenticate implementation of Authenticator

func (NoAuthAuthenticator) GetCode

func (a NoAuthAuthenticator) GetCode() uint8

GetCode implementation of Authenticator

type PermitCommand

type PermitCommand struct {
	EnableConnect   bool
	EnableBind      bool
	EnableAssociate bool
}

PermitCommand is an implementation of the RuleSet which enables filtering supported commands

func (*PermitCommand) Allow

func (p *PermitCommand) Allow(ctx context.Context, req *Request) (context.Context, bool)

Allow ..

type Request

type Request struct {
	// Protocol version
	Version uint8
	// Requested command
	Command uint8
	// AuthContext provided during negotiation
	AuthContext *AuthContext
	// AddrSpec of the the network that sent the request
	RemoteAddr *AddrSpec
	// AddrSpec of the desired destination
	DestAddr *AddrSpec
	// contains filtered or unexported fields
}

A Request represents request received by a server

func NewRequest

func NewRequest(bufConn io.Reader) (*Request, error)

NewRequest creates a new Request from the tcp connection

type RuleSet

type RuleSet interface {
	Allow(ctx context.Context, req *Request) (context.Context, bool)
}

RuleSet is used to provide custom rules to allow or prohibit actions

func PermitAll

func PermitAll() RuleSet

PermitAll returns a RuleSet which allows all types of connections

func PermitNone

func PermitNone() RuleSet

PermitNone returns a RuleSet which disallows all types of connections

type Server

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

Server is responsible for accepting connections and handling the details of the SOCKS5 protocol

func New

func New(conf *Config) (*Server, error)

New creates a new Server and potentially returns an error

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(network, addr string) error

ListenAndServe is used to create a listener and serve on it

func (*Server) Serve

func (s *Server) Serve(l net.Listener) error

Serve is used to serve connections from a listener

func (*Server) ServeConn

func (s *Server) ServeConn(conn net.Conn) error

ServeConn is used to serve a single connection.

type StaticCredentials

type StaticCredentials map[string]string

StaticCredentials enables using a map directly as a credential store

func (StaticCredentials) Valid

func (s StaticCredentials) Valid(user, password string) bool

Valid ...

type UserPassAuthenticator

type UserPassAuthenticator struct {
	Credentials CredentialStore
}

UserPassAuthenticator is used to handle username/password based authentication

func (UserPassAuthenticator) Authenticate

func (a UserPassAuthenticator) Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)

Authenticate implementation of Authenticator

func (UserPassAuthenticator) GetCode

func (a UserPassAuthenticator) GetCode() uint8

GetCode implementation of Authenticator