client.go

Documentation: golang.org/x/crypto/ssh

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package ssh
     6  
     7  import (
     8  	"bytes"
     9  	"errors"
    10  	"fmt"
    11  	"net"
    12  	"os"
    13  	"sync"
    14  	"time"
    15  )
    16  
    17  // Client implements a traditional SSH client that supports shells,
    18  // subprocesses, TCP port/streamlocal forwarding and tunneled dialing.
    19  type Client struct {
    20  	Conn
    21  
    22  	handleForwardsOnce sync.Once // guards calling (*Client).handleForwards
    23  
    24  	forwards        forwardList // forwarded tcpip connections from the remote side
    25  	mu              sync.Mutex
    26  	channelHandlers map[string]chan NewChannel
    27  }
    28  
    29  // HandleChannelOpen returns a channel on which NewChannel requests
    30  // for the given type are sent. If the type already is being handled,
    31  // nil is returned. The channel is closed when the connection is closed.
    32  func (c *Client) HandleChannelOpen(channelType string) <-chan NewChannel {
    33  	c.mu.Lock()
    34  	defer c.mu.Unlock()
    35  	if c.channelHandlers == nil {
    36  		// The SSH channel has been closed.
    37  		c := make(chan NewChannel)
    38  		close(c)
    39  		return c
    40  	}
    41  
    42  	ch := c.channelHandlers[channelType]
    43  	if ch != nil {
    44  		return nil
    45  	}
    46  
    47  	ch = make(chan NewChannel, chanSize)
    48  	c.channelHandlers[channelType] = ch
    49  	return ch
    50  }
    51  
    52  // NewClient creates a Client on top of the given connection.
    53  func NewClient(c Conn, chans <-chan NewChannel, reqs <-chan *Request) *Client {
    54  	conn := &Client{
    55  		Conn:            c,
    56  		channelHandlers: make(map[string]chan NewChannel, 1),
    57  	}
    58  
    59  	go conn.handleGlobalRequests(reqs)
    60  	go conn.handleChannelOpens(chans)
    61  	go func() {
    62  		conn.Wait()
    63  		conn.forwards.closeAll()
    64  	}()
    65  	return conn
    66  }
    67  
    68  // NewClientConn establishes an authenticated SSH connection using c
    69  // as the underlying transport.  The Request and NewChannel channels
    70  // must be serviced or the connection will hang.
    71  func NewClientConn(c net.Conn, addr string, config *ClientConfig) (Conn, <-chan NewChannel, <-chan *Request, error) {
    72  	fullConf := *config
    73  	fullConf.SetDefaults()
    74  	if fullConf.HostKeyCallback == nil {
    75  		c.Close()
    76  		return nil, nil, nil, errors.New("ssh: must specify HostKeyCallback")
    77  	}
    78  
    79  	conn := &connection{
    80  		sshConn: sshConn{conn: c, user: fullConf.User},
    81  	}
    82  
    83  	if err := conn.clientHandshake(addr, &fullConf); err != nil {
    84  		c.Close()
    85  		return nil, nil, nil, fmt.Errorf("ssh: handshake failed: %w", err)
    86  	}
    87  	conn.mux = newMux(conn.transport)
    88  	return conn, conn.mux.incomingChannels, conn.mux.incomingRequests, nil
    89  }
    90  
    91  // clientHandshake performs the client side key exchange. See RFC 4253 Section
    92  // 7.
    93  func (c *connection) clientHandshake(dialAddress string, config *ClientConfig) error {
    94  	if config.ClientVersion != "" {
    95  		c.clientVersion = []byte(config.ClientVersion)
    96  	} else {
    97  		c.clientVersion = []byte(packageVersion)
    98  	}
    99  	var err error
   100  	c.serverVersion, err = exchangeVersions(c.sshConn.conn, c.clientVersion)
   101  	if err != nil {
   102  		return err
   103  	}
   104  
   105  	c.transport = newClientTransport(
   106  		newTransport(c.sshConn.conn, config.Rand, true /* is client */),
   107  		c.clientVersion, c.serverVersion, config, dialAddress, c.sshConn.RemoteAddr())
   108  	if err := c.transport.waitSession(); err != nil {
   109  		return err
   110  	}
   111  
   112  	c.sessionID = c.transport.getSessionID()
   113  	return c.clientAuthenticate(config)
   114  }
   115  
   116  // verifyHostKeySignature verifies the host key obtained in the key exchange.
   117  // algo is the negotiated algorithm, and may be a certificate type.
   118  func verifyHostKeySignature(hostKey PublicKey, algo string, result *kexResult) error {
   119  	sig, rest, ok := parseSignatureBody(result.Signature)
   120  	if len(rest) > 0 || !ok {
   121  		return errors.New("ssh: signature parse error")
   122  	}
   123  
   124  	if a := underlyingAlgo(algo); sig.Format != a {
   125  		return fmt.Errorf("ssh: invalid signature algorithm %q, expected %q", sig.Format, a)
   126  	}
   127  
   128  	return hostKey.Verify(result.H, sig)
   129  }
   130  
   131  // NewSession opens a new Session for this client. (A session is a remote
   132  // execution of a program.)
   133  func (c *Client) NewSession() (*Session, error) {
   134  	ch, in, err := c.OpenChannel("session", nil)
   135  	if err != nil {
   136  		return nil, err
   137  	}
   138  	return newSession(ch, in)
   139  }
   140  
   141  func (c *Client) handleGlobalRequests(incoming <-chan *Request) {
   142  	for r := range incoming {
   143  		// This handles keepalive messages and matches
   144  		// the behaviour of OpenSSH.
   145  		r.Reply(false, nil)
   146  	}
   147  }
   148  
   149  // handleChannelOpens channel open messages from the remote side.
   150  func (c *Client) handleChannelOpens(in <-chan NewChannel) {
   151  	for ch := range in {
   152  		c.mu.Lock()
   153  		handler := c.channelHandlers[ch.ChannelType()]
   154  		c.mu.Unlock()
   155  
   156  		if handler != nil {
   157  			handler <- ch
   158  		} else {
   159  			ch.Reject(UnknownChannelType, fmt.Sprintf("unknown channel type: %v", ch.ChannelType()))
   160  		}
   161  	}
   162  
   163  	c.mu.Lock()
   164  	for _, ch := range c.channelHandlers {
   165  		close(ch)
   166  	}
   167  	c.channelHandlers = nil
   168  	c.mu.Unlock()
   169  }
   170  
   171  // Dial starts a client connection to the given SSH server. It is a
   172  // convenience function that connects to the given network address,
   173  // initiates the SSH handshake, and then sets up a Client.  For access
   174  // to incoming channels and requests, use net.Dial with NewClientConn
   175  // instead.
   176  func Dial(network, addr string, config *ClientConfig) (*Client, error) {
   177  	conn, err := net.DialTimeout(network, addr, config.Timeout)
   178  	if err != nil {
   179  		return nil, err
   180  	}
   181  	c, chans, reqs, err := NewClientConn(conn, addr, config)
   182  	if err != nil {
   183  		return nil, err
   184  	}
   185  	return NewClient(c, chans, reqs), nil
   186  }
   187  
   188  // HostKeyCallback is the function type used for verifying server
   189  // keys.  A HostKeyCallback must return nil if the host key is OK, or
   190  // an error to reject it. It receives the hostname as passed to Dial
   191  // or NewClientConn. The remote address is the RemoteAddr of the
   192  // net.Conn underlying the SSH connection.
   193  type HostKeyCallback func(hostname string, remote net.Addr, key PublicKey) error
   194  
   195  // BannerCallback is the function type used for treat the banner sent by
   196  // the server. A BannerCallback receives the message sent by the remote server.
   197  type BannerCallback func(message string) error
   198  
   199  // A ClientConfig structure is used to configure a Client. It must not be
   200  // modified after having been passed to an SSH function.
   201  type ClientConfig struct {
   202  	// Config contains configuration that is shared between clients and
   203  	// servers.
   204  	Config
   205  
   206  	// User contains the username to authenticate as.
   207  	User string
   208  
   209  	// Auth contains possible authentication methods to use with the
   210  	// server. Only the first instance of a particular RFC 4252 method will
   211  	// be used during authentication.
   212  	Auth []AuthMethod
   213  
   214  	// HostKeyCallback is called during the cryptographic
   215  	// handshake to validate the server's host key. The client
   216  	// configuration must supply this callback for the connection
   217  	// to succeed. The functions InsecureIgnoreHostKey or
   218  	// FixedHostKey can be used for simplistic host key checks.
   219  	HostKeyCallback HostKeyCallback
   220  
   221  	// BannerCallback is called during the SSH dance to display a custom
   222  	// server's message. The client configuration can supply this callback to
   223  	// handle it as wished. The function BannerDisplayStderr can be used for
   224  	// simplistic display on Stderr.
   225  	BannerCallback BannerCallback
   226  
   227  	// ClientVersion contains the version identification string that will
   228  	// be used for the connection. If empty, a reasonable default is used.
   229  	ClientVersion string
   230  
   231  	// HostKeyAlgorithms lists the public key algorithms that the client will
   232  	// accept from the server for host key authentication, in order of
   233  	// preference. If empty, a reasonable default is used. Any
   234  	// string returned from a PublicKey.Type method may be used, or
   235  	// any of the CertAlgo and KeyAlgo constants.
   236  	HostKeyAlgorithms []string
   237  
   238  	// Timeout is the maximum amount of time for the TCP connection to establish.
   239  	//
   240  	// A Timeout of zero means no timeout.
   241  	Timeout time.Duration
   242  }
   243  
   244  // InsecureIgnoreHostKey returns a function that can be used for
   245  // ClientConfig.HostKeyCallback to accept any host key. It should
   246  // not be used for production code.
   247  func InsecureIgnoreHostKey() HostKeyCallback {
   248  	return func(hostname string, remote net.Addr, key PublicKey) error {
   249  		return nil
   250  	}
   251  }
   252  
   253  type fixedHostKey struct {
   254  	key PublicKey
   255  }
   256  
   257  func (f *fixedHostKey) check(hostname string, remote net.Addr, key PublicKey) error {
   258  	if f.key == nil {
   259  		return fmt.Errorf("ssh: required host key was nil")
   260  	}
   261  	if !bytes.Equal(key.Marshal(), f.key.Marshal()) {
   262  		return fmt.Errorf("ssh: host key mismatch")
   263  	}
   264  	return nil
   265  }
   266  
   267  // FixedHostKey returns a function for use in
   268  // ClientConfig.HostKeyCallback to accept only a specific host key.
   269  func FixedHostKey(key PublicKey) HostKeyCallback {
   270  	hk := &fixedHostKey{key}
   271  	return hk.check
   272  }
   273  
   274  // BannerDisplayStderr returns a function that can be used for
   275  // ClientConfig.BannerCallback to display banners on os.Stderr.
   276  func BannerDisplayStderr() BannerCallback {
   277  	return func(banner string) error {
   278  		_, err := os.Stderr.WriteString(banner)
   279  
   280  		return err
   281  	}
   282  }
   283
View as plain text