Documentation

Overview

    Package sshtest provides support code for testing the host package.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    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 {
                                            	Srv         *SSHServer
                                            	UserKeyFile string
                                            }

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

                                              func NewTestData

                                              func NewTestData(userKey, hostKey *rsa.PrivateKey, handler 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
                                                          )