sshtest

Documentation

Overview

Package sshtest provides support code for testing the host package.

Index

• func ConnectToServer(ctx context.Context, srv *SSHServer, key *rsa.PrivateKey, base *ssh.Options) (*ssh.Conn, error)
• func GenerateKeys(bits int) (userKey, hostKey *rsa.PrivateKey, err error)
• func MustGenerateKeys() (userKey, hostKey *rsa.PrivateKey)
• func WriteKey(key *rsa.PrivateKey) (path string, err error)
• type ExecHandler
• type ExecReq
  • func (e *ExecReq) CloseOutput() error
  • func (e *ExecReq) End(status int) error
  • func (e *ExecReq) Read(data []byte) (int, error)
  • func (e *ExecReq) RunRealCmd() int
  • func (e *ExecReq) Start(success bool) error
  • func (e *ExecReq) Stderr() io.ReadWriter
  • func (e *ExecReq) Write(data []byte) (int, error)
• type SSHServer
  • func NewSSHServer(pk *rsa.PublicKey, hk *rsa.PrivateKey, handler ExecHandler) (*SSHServer, error)
  • func (s *SSHServer) Addr() net.Addr
  • func (s *SSHServer) AnswerPings(v bool)
  • func (s *SSHServer) Close() error
  • func (s *SSHServer) RejectConns(n int)
  • func (s *SSHServer) SessionDelay(d time.Duration)
• type TestData
  • func NewTestData(handlers ...ExecHandler) *TestData
  • func (d *TestData) Close()
• type TestDataConn
  • func NewTestDataConn(t *testing.T) *TestDataConn
  • func (td *TestDataConn) Close()
• type TimeoutType

Functions

func ConnectToServer

func ConnectToServer(ctx context.Context, srv *SSHServer, key *rsa.PrivateKey, base *ssh.Options) (*ssh.Conn, error)

ConnectToServer establishes a connection to srv using key. base is used as a base set of options.

func GenerateKeys

func GenerateKeys(bits int) (userKey, hostKey *rsa.PrivateKey, err error)

GenerateKeys generates SSH user and host keys of size bits. This can be time-consuming, so a test file may want to only call this once in its init function and reuse the results.

func MustGenerateKeys

func MustGenerateKeys() (userKey, hostKey *rsa.PrivateKey)

MustGenerateKeys can be called from a test file's init function to generate 1024-bit user and host keys. Panics on error.

func WriteKey

func WriteKey(key *rsa.PrivateKey) (path string, err error)

WriteKey writes key to a temporary file and returns its path. The caller is responsible for unlinking the temp file when complete.

Types

type ExecHandler

type ExecHandler func(req *ExecReq)

ExecHandler is a function that will be called repeatedly to handle "exec" requests. It will be called concurrently on multiple goroutines if multiple overlapping requests are received.

type ExecReq

type ExecReq struct {
	// Cmd contains the command line to be executed.
	Cmd string
	// contains filtered or unexported fields
}

ExecReq is used to service an "exec" request. See RFC 4254 6.5, "Starting a Shell or a Command".

func (*ExecReq) CloseOutput

func (e *ExecReq) CloseOutput() error

CloseOutput closes stdout and stderr.

func (*ExecReq) End

func (e *ExecReq) End(status int) error

End reports the command's status code after execution finishes.

func (*ExecReq) Read

func (e *ExecReq) Read(data []byte) (int, error)

Read reads up to len(data) bytes of input supplied by the SSH client. The data should be passed to the executed command's stdin.

func (*ExecReq) RunRealCmd

func (e *ExecReq) RunRealCmd() int

RunRealCmd runs e.Cmd synchronously, passing stdout, stderr, and stdin appropriately. It calls CloseOutput on completion and returns the process's status code. Callers should call Start(true) before RunRealCmd and End (with the returned status code) after. Callers must validate commands via an out-of-band mechanism before calling this; see host.SSH.AnnounceCmd.

func (*ExecReq) Start

func (e *ExecReq) Start(success bool) error

Start sends a reply to the request reporting the start of the command. If success is false, no further methods should be called. Otherwise, End should be called after the command finishes.

func (*ExecReq) Stderr

func (e *ExecReq) Stderr() io.ReadWriter

Stderr returns a ReadWriter used to write stderr produced by the executed command. It cannot be called after CloseOutput.

func (*ExecReq) Write

func (e *ExecReq) Write(data []byte) (int, error)

Write writes stdout produced by the executed command. It cannot be called after CloseOutput.

type SSHServer

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

SSHServer implements an SSH server based on the ssh package's NewServerConn example that listens on localhost and performs authentication via an RSA keypair.

Only "exec" requests and pings (using SSH_MSG_IGNORE) are supported. "exec" requests are handled using a caller-supplied function.

func NewSSHServer

func NewSSHServer(pk *rsa.PublicKey, hk *rsa.PrivateKey, handler ExecHandler) (*SSHServer, error)

NewSSHServer creates an SSH server using host key hk and accepting public key authentication using pk. A random port bound to the local IPv4 interface is used.

func (*SSHServer) Addr

func (s *SSHServer) Addr() net.Addr

Addr returns the address on which the server is listening.

func (*SSHServer) AnswerPings

func (s *SSHServer) AnswerPings(v bool)

AnswerPings controls whether the server should reply to SSH_MSG_IGNORE ping requests or ignore them.

func (*SSHServer) Close

func (s *SSHServer) Close() error

Close instructs the server to stop listening for connections.

func (*SSHServer) RejectConns

func (s *SSHServer) RejectConns(n int)

RejectConns instructs the server to reject the next n connections.

func (*SSHServer) SessionDelay

func (s *SSHServer) SessionDelay(d time.Duration)

SessionDelay configures a delay used by the server before starting a new session.

type TestData

type TestData struct {
	Srvs        []*SSHServer
	UserKeyFile string
}

TestData contains common data that can be used by tests that interact with an SSHServer.

func NewTestData

func NewTestData(handlers ...ExecHandler) *TestData

NewTestData initializes and returns a TestData struct. Panics on error.

func (*TestData) Close

func (d *TestData) Close()

Close stops the SSHServer and deletes the user key file.

type TestDataConn

type TestDataConn struct {
	Srv *SSHServer // local SSH server
	// Hst is a connection to srv.
	Hst *ssh.Conn

	// Ctx is used for performaing operations using Hst.
	Ctx context.Context
	// Cancel cancels Ctx to simulate a timeout.
	Cancel func()

	// ExecTimeout directs how "exec" requests should time out.
	ExecTimeout TimeoutType
}

TestDataConn wraps data common to all tests. Whereas TastData only manages SSHServer it additionally owns connection to the server.

func NewTestDataConn

func NewTestDataConn(t *testing.T) *TestDataConn

NewTestDataConn sets up local SSH server and connection to it, and returns them together as a TestDataConn struct. Caller must call Close after use.

func (*TestDataConn) Close

func (td *TestDataConn) Close()

Close releases resources associated with td.

type TimeoutType

type TimeoutType int

TimeoutType describes different types of timeouts that can be simulated during SSH "exec" requests.

const (
	// NoTimeout indicates that TestData.Ctx shouldn't be canceled.
	NoTimeout TimeoutType = iota
	// StartTimeout indicates that TestData.Ctx should be canceled before the command starts.
	StartTimeout
	// EndTimeout indicates that TestData.Ctx should be canceled after the command runs but before its status is returned.
	EndTimeout
)