ssh

package
v0.0.0-...-33b7a6c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 25, 2013 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package ssh implements an SSH client and server.

SSH is a transport security protocol, an authentication protocol and a family of application protocols. The most typical application level protocol is a remote shell and this is specifically implemented. However, the multiplexed nature of SSH is exposed to users that wish to support others.

An SSH server is represented by a ServerConfig, which holds certificate details and handles authentication of ServerConns. 

config := new(ssh.ServerConfig)
config.PubKeyCallback = pubKeyAuth
config.PasswordCallback = passwordAuth

pemBytes, err := ioutil.ReadFile("id_rsa")
if err != nil {
	panic("Failed to load private key")
}
err = config.SetRSAPrivateKey(pemBytes)
if err != nil {
	panic("Failed to parse private key")
}

Once a ServerConfig has been configured, connections can be accepted. 

listener := Listen("tcp", "0.0.0.0:2022", config)
sConn, err := listener.Accept()
if err != nil {
	panic("failed to accept incoming connection")
}
if err := sConn.Handshake(conn); err != nil {
	panic("failed to handshake")
}

An SSH connection multiplexes several channels, which must be accepted themselves: 

for {
	channel, err := sConn.Accept()
	if err != nil {
		panic("error from Accept")
	}

	...
}

Accept reads from the connection, demultiplexes packets to their corresponding channels and returns when a new channel request is seen. Some goroutine must always be calling Accept; otherwise no messages will be forwarded to the channels.

Channels have a type, depending on the application level protocol intended. In the case of a shell, the type is "session" and ServerShell may be used to present a simple terminal interface. 

if channel.ChannelType() != "session" {
	channel.Reject(UnknownChannelType, "unknown channel type")
	return
}
channel.Accept()

term := terminal.NewTerminal(channel, "> ")
serverTerm := &ssh.ServerTerminal{
	Term: term,
	Channel: channel,
}
go func() {
	defer channel.Close()
	for {
		line, err := serverTerm.ReadLine()
		if err != nil {
			break
		}
		println(line)
	}
	return
}()

To authenticate with the remote server you must pass at least one implementation of ClientAuth via the Auth field in ClientConfig. 

// password implements the ClientPassword interface
type password string

func (p password) Password(user string) (string, error) {
	return string(p), nil
}

config := &ssh.ClientConfig {
	User: "username",
	Auth: []ClientAuth {
		// ClientAuthPassword wraps a ClientPassword implementation
		// in a type that implements ClientAuth.
		ClientAuthPassword(password("yourpassword")),
	}
}

An SSH client is represented with a ClientConn. Currently only the "password" authentication method is supported. 

config := &ClientConfig{
	User: "username",
	Auth: []ClientAuth{ ... },
}
client, err := Dial("yourserver.com:22", config)

Each ClientConn can support multiple interactive sessions, represented by a Session. 

session, err := client.NewSession()

Once a Session is created, you can execute a single command on the remote side using the Exec method. 

b := bytes.NewBuffer()
session.Stdin = b
if err := session.Run("/usr/bin/whoami"); err != nil {
	panic("Failed to exec: " + err.String())
}
fmt.Println(bytes.String())
session.Close()

Index

Constants

This section is empty.

Variables

View Source 
var DefaultCipherOrder = []string{
	"aes128-ctr", "aes192-ctr", "aes256-ctr",
	"arcfour256", "arcfour128",
}

Specifies a default set of ciphers and a preference order. This is based on OpenSSH's default client preference order, minus algorithms that are not implemented.

Functions

This section is empty.

Types

type Channel 

type Channel interface {
	// Accept accepts the channel creation request.
	Accept() error
	// Reject rejects the channel creation request. After calling this, no
	// other methods on the Channel may be called. If they are then the
	// peer is likely to signal a protocol error and drop the connection.
	Reject(reason RejectionReason, message string) error

	// Read may return a ChannelRequest as an error.
	Read(data []byte) (int, error)
	Write(data []byte) (int, error)
	Close() error

	// AckRequest either sends an ack or nack to the channel request.
	AckRequest(ok bool) error

	// ChannelType returns the type of the channel, as supplied by the
	// client.
	ChannelType() string
	// ExtraData returns the arbitary payload for this channel, as supplied
	// by the client. This data is specific to the channel type.
	ExtraData() []byte
}

A Channel is an ordered, reliable, duplex stream that is multiplexed over an SSH connection.

type ChannelRequest 

type ChannelRequest struct {
	Request   string
	WantReply bool
	Payload   []byte
}

ChannelRequest represents a request sent on a channel, outside of the normal stream of bytes. It may result from calling Read on a Channel.

func (ChannelRequest) Error 

func (c ChannelRequest) Error() string

type ClientAuth 

type ClientAuth interface {
	// contains filtered or unexported methods
}

A ClientAuth represents an instance of an RFC 4252 authentication method.

func ClientAuthKeyring 

func ClientAuthKeyring(impl ClientKeyring) ClientAuth

ClientAuthKeyring returns a ClientAuth using public key authentication.

func ClientAuthPassword 

func ClientAuthPassword(impl ClientPassword) ClientAuth

ClientAuthPassword returns a ClientAuth using password authentication.

type ClientConfig 

type ClientConfig struct {
	// Rand provides the source of entropy for key exchange. If Rand is
	// nil, the cryptographic random reader in package crypto/rand will
	// be used.
	Rand io.Reader

	// The username to authenticate.
	User string

	// A slice of ClientAuth methods. Only the first instance
	// of a particular RFC 4252 method will be used during authentication.
	Auth []ClientAuth

	// Cryptographic-related configuration.
	Crypto CryptoConfig
}

A ClientConfig structure is used to configure a ClientConn. After one has been passed to an SSH function it must not be modified.

type ClientConn 

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

ClientConn represents the client side of an SSH connection.

func Client 

func Client(c net.Conn, config *ClientConfig) (*ClientConn, error)

Client returns a new SSH client connection using c as the underlying transport.

func Dial 

func Dial(network, addr string, config *ClientConfig) (*ClientConn, error)

Dial connects to the given network address using net.Dial and then initiates a SSH handshake, returning the resulting client connection.

func (*ClientConn) Dial 

func (c *ClientConn) Dial(n, addr string) (net.Conn, error)

Dial initiates a connection to the addr from the remote host. addr is resolved using net.ResolveTCPAddr before connection. This could allow an observer to observe the DNS name of the remote host. Consider using ssh.DialTCP to avoid this.

func (*ClientConn) DialTCP 

func (c *ClientConn) DialTCP(n string, laddr, raddr *net.TCPAddr) (net.Conn, error)

DialTCP connects to the remote address raddr on the network net, which must be "tcp", "tcp4", or "tcp6". If laddr is not nil, it is used as the local address for the connection.

func (*ClientConn) NewSession 

func (c *ClientConn) NewSession() (*Session, error)

NewSession returns a new interactive session on the remote host.

type ClientKeyring 

type ClientKeyring interface {
	// Key returns the i'th rsa.Publickey or dsa.Publickey, or nil if
	// no key exists at i.
	Key(i int) (key interface{}, err error)

	// Sign returns a signature of the given data using the i'th key
	// and the supplied random source.
	Sign(i int, rand io.Reader, data []byte) (sig []byte, err error)
}

ClientKeyring implements access to a client key ring.

type ClientPassword 

type ClientPassword interface {
	// Password returns the password to use for user.
	Password(user string) (password string, err error)
}

A ClientPassword implements access to a client's passwords.

type CryptoConfig 

type CryptoConfig struct {
	// The allowed cipher algorithms. If unspecified then DefaultCipherOrder is
	// used.
	Ciphers []string
}

Cryptographic configuration common to both ServerConfig and ClientConfig.

type ExitError 

type ExitError struct {
	Waitmsg
}

An ExitError reports unsuccessful completion of a remote command.

func (*ExitError) Error 

func (e *ExitError) Error() string

type Listener 

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

A Listener implements a network listener (net.Listener) for SSH connections.

func Listen 

func Listen(network, addr string, config *ServerConfig) (*Listener, error)

Listen creates an SSH listener accepting connections on the given network address using net.Listen.

func (*Listener) Accept 

func (l *Listener) Accept() (*ServerConn, error)

Accept waits for and returns the next incoming SSH connection. The receiver should call Handshake() in another goroutine to avoid blocking the accepter.

func (*Listener) Addr 

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address.

func (*Listener) Close 

func (l *Listener) Close() error

Close closes the listener.

type ParseError 

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

ParseError results from a malformed SSH message.

func (ParseError) Error 

func (p ParseError) Error() string

type RejectionReason 

type RejectionReason int

RejectionReason is an enumeration used when rejecting channel creation requests. See RFC 4254, section 5.1. 

const (
	Prohibited RejectionReason = iota + 1
	ConnectionFailed
	UnknownChannelType
	ResourceShortage
)

type ServerConfig 

type ServerConfig struct {

	// Rand provides the source of entropy for key exchange. If Rand is
	// nil, the cryptographic random reader in package crypto/rand will
	// be used.
	Rand io.Reader

	// NoClientAuth is true if clients are allowed to connect without
	// authenticating.
	NoClientAuth bool

	// PasswordCallback, if non-nil, is called when a user attempts to
	// authenticate using a password. It may be called concurrently from
	// several goroutines.
	PasswordCallback func(conn *ServerConn, user, password string) bool

	// PublicKeyCallback, if non-nil, is called when a client attempts public
	// key authentication. It must return true iff the given public key is
	// valid for the given user.
	PublicKeyCallback func(conn *ServerConn, user, algo string, pubkey []byte) bool

	// Cryptographic-related configuration.
	Crypto CryptoConfig
	// contains filtered or unexported fields
}

func (*ServerConfig) SetRSAPrivateKey 

func (s *ServerConfig) SetRSAPrivateKey(pemBytes []byte) error

SetRSAPrivateKey sets the private key for a Server. A Server must have a private key configured in order to accept connections. The private key must be in the form of a PEM encoded, PKCS#1, RSA private key. The file "id_rsa" typically contains such a key.

type ServerConn 

type ServerConn struct {

	// User holds the successfully authenticated user name.
	// It is empty if no authentication is used.  It is populated before
	// any authentication callback is called and not assigned to after that.
	User string
	// contains filtered or unexported fields
}

A ServerConn represents an incomming connection.

func Server 

func Server(c net.Conn, config *ServerConfig) *ServerConn

Server returns a new SSH server connection using c as the underlying transport.

func (*ServerConn) Accept 

func (s *ServerConn) Accept() (Channel, error)

Accept reads and processes messages on a ServerConn. It must be called in order to demultiplex messages to any resulting Channels.

func (*ServerConn) Handshake 

func (s *ServerConn) Handshake() error

Handshake performs an SSH transport and client authentication on the given ServerConn.

type ServerTerminal 

type ServerTerminal struct {
	Term    Terminal
	Channel Channel
}

ServerTerminal contains the state for running a terminal that is capable of reading lines of input.

func (*ServerTerminal) ReadLine 

func (ss *ServerTerminal) ReadLine() (line string, err error)

ReadLine returns a line of input from the terminal.

func (*ServerTerminal) Write 

func (ss *ServerTerminal) Write(buf []byte) (n int, err error)

type Session 

type Session struct {
	// Stdin specifies the remote process's standard input.
	// If Stdin is nil, the remote process reads from an empty
	// bytes.Buffer.
	Stdin io.Reader

	// Stdout and Stderr specify the remote process's standard
	// output and error.
	//
	// If either is nil, Run connects the corresponding file
	// descriptor to an instance of ioutil.Discard. There is a
	// fixed amount of buffering that is shared for the two streams.
	// If either blocks it may eventually cause the remote
	// command to block.
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

A Session represents a connection to a remote command or shell.

func (Session) Close 

func (c Session) Close() error

Close closes the channel. This does not close the underlying connection.

func (*Session) RequestPty 

func (s *Session) RequestPty(term string, h, w int) error

RequestPty requests the association of a pty with the session on the remote host.

func (*Session) Run 

func (s *Session) Run(cmd string) error

Run runs cmd on the remote host. Typically, the remote server passes cmd to the shell for interpretation. A Session only accepts one call to Run, Start or Shell.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the command fails to run or doesn't complete successfully, the error is of type *ExitError. Other error types may be returned for I/O problems.

func (*Session) Setenv 

func (s *Session) Setenv(name, value string) error

Setenv sets an environment variable that will be applied to any command executed by Shell or Run.

func (*Session) Shell 

func (s *Session) Shell() error

Shell starts a login shell on the remote host. A Session only accepts one call to Run, Start or Shell.

func (*Session) Signal 

func (s *Session) Signal(sig Signal) error

Signal sends the given signal to the remote process. sig is one of the SIG* constants.

func (*Session) Start 

func (s *Session) Start(cmd string) error

Start runs cmd on the remote host. Typically, the remote server passes cmd to the shell for interpretation. A Session only accepts one call to Run, Start or Shell.

func (*Session) StderrPipe 

func (s *Session) StderrPipe() (io.Reader, error)

StderrPipe returns a pipe that will be connected to the remote command's standard error when the command starts. There is a fixed amount of buffering that is shared between stdout and stderr streams. If the StderrPipe reader is not serviced fast enought it may eventually cause the remote command to block.

func (*Session) StdinPipe 

func (s *Session) StdinPipe() (io.WriteCloser, error)

StdinPipe returns a pipe that will be connected to the remote command's standard input when the command starts.

func (*Session) StdoutPipe 

func (s *Session) StdoutPipe() (io.Reader, error)

StdoutPipe returns a pipe that will be connected to the remote command's standard output when the command starts. There is a fixed amount of buffering that is shared between stdout and stderr streams. If the StdoutPipe reader is not serviced fast enought it may eventually cause the remote command to block.

func (*Session) Wait 

func (s *Session) Wait() error

Wait waits for the remote command to exit.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the command fails to run or doesn't complete successfully, the error is of type *ExitError. Other error types may be returned for I/O problems.

type Signal 

type Signal string
const (
	SIGABRT Signal = "ABRT"
	SIGALRM Signal = "ALRM"
	SIGFPE  Signal = "FPE"
	SIGHUP  Signal = "HUP"
	SIGILL  Signal = "ILL"
	SIGINT  Signal = "INT"
	SIGKILL Signal = "KILL"
	SIGPIPE Signal = "PIPE"
	SIGQUIT Signal = "QUIT"
	SIGSEGV Signal = "SEGV"
	SIGTERM Signal = "TERM"
	SIGUSR1 Signal = "USR1"
	SIGUSR2 Signal = "USR2"
)

POSIX signals as listed in RFC 4254 Section 6.10.

type Terminal 

type Terminal interface {
	ReadLine() (line string, err error)
	SetSize(x, y int)
	Write([]byte) (int, error)
}

A Terminal is capable of parsing and generating virtual terminal data from an SSH client.

type UnexpectedMessageError 

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

UnexpectedMessageError results when the SSH message that we received didn't match what we wanted.

func (UnexpectedMessageError) Error 

func (u UnexpectedMessageError) Error() string

type Waitmsg 

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

Waitmsg stores the information about an exited remote command as reported by Wait.

func (Waitmsg) ExitStatus 

func (w Waitmsg) ExitStatus() int

ExitStatus returns the exit status of the remote command.

func (Waitmsg) Lang 

func (w Waitmsg) Lang() string

Lang returns the language tag. See RFC 3066

func (Waitmsg) Msg 

func (w Waitmsg) Msg() string

Msg returns the exit message given by the remote command

func (Waitmsg) Signal 

func (w Waitmsg) Signal() string

Signal returns the exit signal of the remote command if it was terminated violently.

func (Waitmsg) String 

func (w Waitmsg) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.