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.
16 // Client implements a traditional SSH client that supports shells,
17 // subprocesses, TCP port/streamlocal forwarding and tunneled dialing.
21 forwards forwardList // forwarded tcpip connections from the remote side
23 channelHandlers map[string]chan NewChannel
26 // HandleChannelOpen returns a channel on which NewChannel requests
27 // for the given type are sent. If the type already is being handled,
28 // nil is returned. The channel is closed when the connection is closed.
29 func (c *Client) HandleChannelOpen(channelType string) <-chan NewChannel {
32 if c.channelHandlers == nil {
33 // The SSH channel has been closed.
34 c := make(chan NewChannel)
39 ch := c.channelHandlers[channelType]
44 ch = make(chan NewChannel, chanSize)
45 c.channelHandlers[channelType] = ch
49 // NewClient creates a Client on top of the given connection.
50 func NewClient(c Conn, chans <-chan NewChannel, reqs <-chan *Request) *Client {
53 channelHandlers: make(map[string]chan NewChannel, 1),
56 go conn.handleGlobalRequests(reqs)
57 go conn.handleChannelOpens(chans)
60 conn.forwards.closeAll()
62 go conn.forwards.handleChannels(conn.HandleChannelOpen("forwarded-tcpip"))
63 go conn.forwards.handleChannels(conn.HandleChannelOpen("forwarded-streamlocal@openssh.com"))
67 // NewClientConn establishes an authenticated SSH connection using c
68 // as the underlying transport. The Request and NewChannel channels
69 // must be serviced or the connection will hang.
70 func NewClientConn(c net.Conn, addr string, config *ClientConfig) (Conn, <-chan NewChannel, <-chan *Request, error) {
72 fullConf.SetDefaults()
73 if fullConf.HostKeyCallback == nil {
75 return nil, nil, nil, errors.New("ssh: must specify HostKeyCallback")
79 sshConn: sshConn{conn: c},
82 if err := conn.clientHandshake(addr, &fullConf); err != nil {
84 return nil, nil, nil, fmt.Errorf("ssh: handshake failed: %v", err)
86 conn.mux = newMux(conn.transport)
87 return conn, conn.mux.incomingChannels, conn.mux.incomingRequests, nil
90 // clientHandshake performs the client side key exchange. See RFC 4253 Section
92 func (c *connection) clientHandshake(dialAddress string, config *ClientConfig) error {
93 if config.ClientVersion != "" {
94 c.clientVersion = []byte(config.ClientVersion)
96 c.clientVersion = []byte(packageVersion)
99 c.serverVersion, err = exchangeVersions(c.sshConn.conn, c.clientVersion)
104 c.transport = newClientTransport(
105 newTransport(c.sshConn.conn, config.Rand, true /* is client */),
106 c.clientVersion, c.serverVersion, config, dialAddress, c.sshConn.RemoteAddr())
107 if err := c.transport.waitSession(); err != nil {
111 c.sessionID = c.transport.getSessionID()
112 return c.clientAuthenticate(config)
115 // verifyHostKeySignature verifies the host key obtained in the key
117 func verifyHostKeySignature(hostKey PublicKey, result *kexResult) error {
118 sig, rest, ok := parseSignatureBody(result.Signature)
119 if len(rest) > 0 || !ok {
120 return errors.New("ssh: signature parse error")
123 return hostKey.Verify(result.H, sig)
126 // NewSession opens a new Session for this client. (A session is a remote
127 // execution of a program.)
128 func (c *Client) NewSession() (*Session, error) {
129 ch, in, err := c.OpenChannel("session", nil)
133 return newSession(ch, in)
136 func (c *Client) handleGlobalRequests(incoming <-chan *Request) {
137 for r := range incoming {
138 // This handles keepalive messages and matches
139 // the behaviour of OpenSSH.
144 // handleChannelOpens channel open messages from the remote side.
145 func (c *Client) handleChannelOpens(in <-chan NewChannel) {
148 handler := c.channelHandlers[ch.ChannelType()]
154 ch.Reject(UnknownChannelType, fmt.Sprintf("unknown channel type: %v", ch.ChannelType()))
159 for _, ch := range c.channelHandlers {
162 c.channelHandlers = nil
166 // Dial starts a client connection to the given SSH server. It is a
167 // convenience function that connects to the given network address,
168 // initiates the SSH handshake, and then sets up a Client. For access
169 // to incoming channels and requests, use net.Dial with NewClientConn
171 func Dial(network, addr string, config *ClientConfig) (*Client, error) {
172 conn, err := net.DialTimeout(network, addr, config.Timeout)
176 c, chans, reqs, err := NewClientConn(conn, addr, config)
180 return NewClient(c, chans, reqs), nil
183 // HostKeyCallback is the function type used for verifying server
184 // keys. A HostKeyCallback must return nil if the host key is OK, or
185 // an error to reject it. It receives the hostname as passed to Dial
186 // or NewClientConn. The remote address is the RemoteAddr of the
187 // net.Conn underlying the the SSH connection.
188 type HostKeyCallback func(hostname string, remote net.Addr, key PublicKey) error
190 // A ClientConfig structure is used to configure a Client. It must not be
191 // modified after having been passed to an SSH function.
192 type ClientConfig struct {
193 // Config contains configuration that is shared between clients and
197 // User contains the username to authenticate as.
200 // Auth contains possible authentication methods to use with the
201 // server. Only the first instance of a particular RFC 4252 method will
202 // be used during authentication.
205 // HostKeyCallback is called during the cryptographic
206 // handshake to validate the server's host key. The client
207 // configuration must supply this callback for the connection
208 // to succeed. The functions InsecureIgnoreHostKey or
209 // FixedHostKey can be used for simplistic host key checks.
210 HostKeyCallback HostKeyCallback
212 // ClientVersion contains the version identification string that will
213 // be used for the connection. If empty, a reasonable default is used.
216 // HostKeyAlgorithms lists the key types that the client will
217 // accept from the server as host key, in order of
218 // preference. If empty, a reasonable default is used. Any
219 // string returned from PublicKey.Type method may be used, or
220 // any of the CertAlgoXxxx and KeyAlgoXxxx constants.
221 HostKeyAlgorithms []string
223 // Timeout is the maximum amount of time for the TCP connection to establish.
225 // A Timeout of zero means no timeout.
226 Timeout time.Duration
229 // InsecureIgnoreHostKey returns a function that can be used for
230 // ClientConfig.HostKeyCallback to accept any host key. It should
231 // not be used for production code.
232 func InsecureIgnoreHostKey() HostKeyCallback {
233 return func(hostname string, remote net.Addr, key PublicKey) error {
238 type fixedHostKey struct {
242 func (f *fixedHostKey) check(hostname string, remote net.Addr, key PublicKey) error {
244 return fmt.Errorf("ssh: required host key was nil")
246 if !bytes.Equal(key.Marshal(), f.key.Marshal()) {
247 return fmt.Errorf("ssh: host key mismatch")
252 // FixedHostKey returns a function for use in
253 // ClientConfig.HostKeyCallback to accept only a specific host key.
254 func FixedHostKey(key PublicKey) HostKeyCallback {
255 hk := &fixedHostKey{key}