socks5

README

go-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
• Rules to do granular filtering of commands
• Custom DNS resolution
• Unit tests

TODO

The package still needs the following:

• Support for the BIND command
• Support for the ASSOCIATE 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
• func ReadBytes(r io.Reader, count int) ([]byte, error)
• func ReadShortString(r io.Reader) (string, error)
• func ReadString(r io.Reader) (string, error)
• func ReadUint32(r io.Reader) (uint32, error)
• func ReadUint8(r io.Reader) (uint8, error)
• func WriteShortString(w io.Writer, str string) error
• func WriteString(w io.Writer, str string) error
• type AddrSpec
  • func (a AddrSpec) Address() string
  • func (a *AddrSpec) String() string
• 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 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)
  • func PerformHandshake(conn net.Conn, authenticators []Authenticator) (*Request, error)
  • func (r *Request) WriteTo(w io.Writer) error
• type RuleSet
  • func PermitAll() RuleSet
  • func PermitNone() RuleSet
• type Server
  • func New(conf *Config) (*Server, error)
  • func (s *Server) HandleRequest(req *Request, conn conn) 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 (
	NoAuth = uint8(0)

	UserPassAuth = uint8(2)
)

const (
	ConnectCommand   = uint8(1)
	BindCommand      = uint8(2)
	AssociateCommand = uint8(3)
)

Variables

var (
	UserAuthFailed  = fmt.Errorf("User authentication failed")
	NoSupportedAuth = fmt.Errorf("No supported authentication mechanism")
)

Functions

func ReadBytes

func ReadBytes(r io.Reader, count int) ([]byte, error)

func ReadShortString

func ReadShortString(r io.Reader) (string, error)

func ReadString

func ReadString(r io.Reader) (string, error)

func ReadUint32

func ReadUint32(r io.Reader) (uint32, error)

func ReadUint8

func ReadUint8(r io.Reader) (uint8, error)

func WriteShortString

func WriteShortString(w io.Writer, str string) error

func WriteString

func WriteString(w io.Writer, str string) error

Types

type AddrSpec

type AddrSpec struct {
	AddressType byte
	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) String

func (a *AddrSpec) String() string

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
}

A Request encapsulates authentication state provided during negotiation

type Authenticator

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

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

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

	// Optional function for dialing out
	Dial func(ctx context.Context, network, addr string) (net.Conn, 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)

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)

func (NoAuthAuthenticator) GetCode

func (a NoAuthAuthenticator) GetCode() uint8

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)

type Request

type Request struct {
	// Protocol version
	Version uint8
	// Requested command
	Command uint8
	// reserved header byte
	Reserved 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

func PerformHandshake

func PerformHandshake(conn net.Conn, authenticators []Authenticator) (*Request, error)

func (*Request) WriteTo

func (r *Request) WriteTo(w io.Writer) error

WriteTo writes the request to the given writer

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 reponsible 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) HandleRequest

func (s *Server) HandleRequest(req *Request, conn conn) error

HandleRequest is used for request processing after authentication

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

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)

func (UserPassAuthenticator) GetCode

func (a UserPassAuthenticator) GetCode() uint8