ssh

Documentation

Index

• Constants
• type ChannelHandler
• type Client
  • func NewClient(config Config) *Client
  • func (c *Client) Start(ctx context.Context) (*govpn.Session, error)
• type Config
• type GlobalRequestHandler
• type Server
  • func NewServer(config ServerConfig) *Server
  • func (s *Server) HandleConn(ctx context.Context, rawConnection net.Conn, onTunnel TunnelSessionHandler) error
  • func (s *Server) RegisterChannelHandler(channelType string, handler ChannelHandler) error
  • func (s *Server) RegisterGlobalRequestHandler(requestType string, handler GlobalRequestHandler) error
  • func (s *Server) RegisterSessionRequestHandler(requestType string, handler SessionRequestHandler) error
  • func (s *Server) Serve(ctx context.Context, listener net.Listener) (*govpn.Session, error)
  • func (s *Server) Start(ctx context.Context) (*govpn.Session, error)
• type ServerConfig
• type ServerSession
  • func (s *ServerSession) SetValue(key string, value any)
  • func (s *ServerSession) Value(key string) (any, bool)
• type ServerUser
• type SessionRequestHandler
• type TunnelRequest
• type TunnelResolver
• type TunnelSessionHandler
• type TunnelSettings

Constants

const (
	TunnelModePointToPoint uint32 = sshTunnelModePointToPoint
	TunnelUnitAny          uint32 = sshTunnelIDAny
)

Types

type ChannelHandler

type ChannelHandler func(context.Context, *gossh.ServerConn, gossh.NewChannel)

ChannelHandler owns an SSH channel request and must accept or reject it. It is used for channel types such as direct-tcpip.

type Client

type Client struct{ Config Config }

func NewClient

func NewClient(config Config) *Client

func (*Client) Start

func (c *Client) Start(ctx context.Context) (*govpn.Session, error)

type Config

type Config struct {
	Server               string
	User                 string
	Password             string
	PrivateKey           []byte
	PrivateKeyPassphrase []byte
	KnownHostsFile       string
	HostKey              []byte
	HostKeyCallback      gossh.HostKeyCallback
	InsecureSkipHostKey  bool
	Address              []string
	MTU                  int
	RemoteTunnel         *int
	RemoteCommand        string
	Timeout              time.Duration
	KeepaliveInterval    time.Duration
	Logger               *log.Logger
}

Config describes an OpenSSH point-to-point TUN client. Address contains the local addresses used by the in-process network stack; the corresponding remote TUN addresses and routes must be configured on the SSH server.

type GlobalRequestHandler

type GlobalRequestHandler func(context.Context, *gossh.ServerConn, *gossh.Request)

GlobalRequestHandler owns an SSH global request, including sending a reply when Request.WantReply is true.

type Server

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

func NewServer

func NewServer(config ServerConfig) *Server

func (*Server) HandleConn

func (s *Server) HandleConn(ctx context.Context, rawConnection net.Conn, onTunnel TunnelSessionHandler) error

HandleConn serves a general-purpose SSH connection and takes ownership of rawConnection. Shell, PTY, SFTP, forwarding, and other registered handlers work even when the peer never opens a TUN channel. onTunnel is called at most once when a userspace tunnel is established.

func (*Server) RegisterChannelHandler

func (s *Server) RegisterChannelHandler(channelType string, handler ChannelHandler) error

RegisterChannelHandler registers a handler for channels such as direct-tcpip. The built-in tun@openssh.com and session dispatchers are reserved.

func (*Server) RegisterGlobalRequestHandler

func (s *Server) RegisterGlobalRequestHandler(requestType string, handler GlobalRequestHandler) error

RegisterGlobalRequestHandler registers an SSH connection-level request handler. The handler owns replies requested by the peer.

func (*Server) RegisterSessionRequestHandler

func (s *Server) RegisterSessionRequestHandler(requestType string, handler SessionRequestHandler) error

RegisterSessionRequestHandler registers a handler for a request on an SSH session channel, for example pty-req, shell, exec, or subsystem.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, listener net.Listener) (*govpn.Session, error)

Serve accepts one SSH connection from listener and takes ownership of the listener. It allows an application to supply its own listening lifecycle.

func (*Server) Start

func (s *Server) Start(ctx context.Context) (*govpn.Session, error)

type ServerConfig

type ServerConfig struct {
	ListenIP                    string
	ListenPort                  int
	HostKey                     []byte
	HostKeyPassphrase           []byte
	Users                       map[string]ServerUser
	PasswordCallback            func(gossh.ConnMetadata, []byte) (*gossh.Permissions, error)
	PublicKeyCallback           func(gossh.ConnMetadata, gossh.PublicKey) (*gossh.Permissions, error)
	KeyboardInteractiveCallback func(gossh.ConnMetadata, gossh.KeyboardInteractiveChallenge) (*gossh.Permissions, error)
	NoClientAuth                bool
	Address                     []string
	MTU                         int
	ResolveTunnel               TunnelResolver
	Timeout                     time.Duration
	KeepaliveInterval           time.Duration
	ServerVersion               string
	Logger                      *log.Logger
}

ServerConfig describes a pure-Go SSH server. Address is used when ResolveTunnel is nil. The callbacks use the native x/crypto/ssh API so an application can attach permissions and external authentication state.

type ServerSession

type ServerSession struct {
	Connection *gossh.ServerConn
	Channel    gossh.Channel
	// contains filtered or unexported fields
}

ServerSession is shared by all request handlers for one SSH session channel. Values allows PTY, shell, exec, and subsystem extensions to share per-session state without global maps.

func (*ServerSession) SetValue

func (s *ServerSession) SetValue(key string, value any)

SetValue stores extension state shared by handlers for this session.

func (*ServerSession) Value

func (s *ServerSession) Value(key string) (any, bool)

Value loads extension state shared by handlers for this session.

type ServerUser

type ServerUser struct {
	Password       string
	AuthorizedKeys [][]byte
}

ServerUser contains the built-in authentication methods for one SSH user. Applications needing certificates, external identity stores, or custom permissions can use ServerConfig callbacks instead.

type SessionRequestHandler

type SessionRequestHandler func(context.Context, *ServerSession, *gossh.Request)

SessionRequestHandler handles requests such as pty-req, shell, exec, and subsystem on an accepted SSH session channel. It owns the request reply.

type TunnelRequest

type TunnelRequest struct {
	Mode uint32
	Unit uint32
}

TunnelRequest is the OpenSSH TUN channel request. Unit may be TunnelUnitAny; it is a logical identifier because the pure-Go server does not create an operating-system TUN interface.

type TunnelResolver

type TunnelResolver func(context.Context, *gossh.ServerConn, TunnelRequest) (TunnelSettings, error)

TunnelResolver authorizes a TUN request and selects settings after SSH authentication has completed.

type TunnelSessionHandler

type TunnelSessionHandler func(context.Context, *gossh.ServerConn, *govpn.Session)

TunnelSessionHandler receives a userspace VPN session opened on an otherwise general-purpose SSH connection. Implementations normally start services on the session and return without closing it.

type TunnelSettings

type TunnelSettings struct {
	Address []string
	MTU     int
}

TunnelSettings selects the addresses and MTU of the server-side userspace stack for an authenticated connection.