github.com/slspeek/camlistore_namedsearch@v0.0.0-20140519202248-ed6f70f7721a/third_party/code.google.com/p/go.crypto/ssh/doc.go (about)

     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  /*
     6  Package ssh implements an SSH client and server.
     7  
     8  SSH is a transport security protocol, an authentication protocol and a
     9  family of application protocols. The most typical application level
    10  protocol is a remote shell and this is specifically implemented.  However,
    11  the multiplexed nature of SSH is exposed to users that wish to support
    12  others.
    13  
    14  An SSH server is represented by a ServerConfig, which holds certificate
    15  details and handles authentication of ServerConns.
    16  
    17  	config := new(ssh.ServerConfig)
    18  	config.PubKeyCallback = pubKeyAuth
    19  	config.PasswordCallback = passwordAuth
    20  
    21  	pemBytes, err := ioutil.ReadFile("id_rsa")
    22  	if err != nil {
    23  		panic("Failed to load private key")
    24  	}
    25  	err = config.SetRSAPrivateKey(pemBytes)
    26  	if err != nil {
    27  		panic("Failed to parse private key")
    28  	}
    29  
    30  Once a ServerConfig has been configured, connections can be accepted.
    31  
    32  	listener := Listen("tcp", "0.0.0.0:2022", config)
    33  	sConn, err := listener.Accept()
    34  	if err != nil {
    35  		panic("failed to accept incoming connection")
    36  	}
    37  	if err := sConn.Handshake(conn); err != nil {
    38  		panic("failed to handshake")
    39  	}
    40  
    41  An SSH connection multiplexes several channels, which must be accepted themselves:
    42  
    43  	for {
    44  		channel, err := sConn.Accept()
    45  		if err != nil {
    46  			panic("error from Accept")
    47  		}
    48  
    49  		...
    50  	}
    51  
    52  Accept reads from the connection, demultiplexes packets to their corresponding
    53  channels and returns when a new channel request is seen. Some goroutine must
    54  always be calling Accept; otherwise no messages will be forwarded to the
    55  channels.
    56  
    57  Channels have a type, depending on the application level protocol intended. In
    58  the case of a shell, the type is "session" and ServerShell may be used to
    59  present a simple terminal interface.
    60  
    61  	if channel.ChannelType() != "session" {
    62  		channel.Reject(UnknownChannelType, "unknown channel type")
    63  		return
    64  	}
    65  	channel.Accept()
    66  
    67  	term := terminal.NewTerminal(channel, "> ")
    68  	serverTerm := &ssh.ServerTerminal{
    69  		Term: term,
    70  		Channel: channel,
    71  	}
    72  	go func() {
    73  		defer channel.Close()
    74  		for {
    75  			line, err := serverTerm.ReadLine()
    76  			if err != nil {
    77  				break
    78  			}
    79  			println(line)
    80  		}
    81  		return
    82  	}()
    83  
    84  To authenticate with the remote server you must pass at least one implementation of 
    85  ClientAuth via the Auth field in ClientConfig.
    86  
    87  	// password implements the ClientPassword interface
    88  	type password string
    89  
    90  	func (p password) Password(user string) (string, error) {
    91  		return string(p), nil
    92  	}
    93  
    94  	config := &ssh.ClientConfig {
    95  		User: "username",
    96  		Auth: []ClientAuth {
    97  			// ClientAuthPassword wraps a ClientPassword implementation
    98  			// in a type that implements ClientAuth.
    99  			ClientAuthPassword(password("yourpassword")),
   100  		}
   101  	}
   102  
   103  An SSH client is represented with a ClientConn. Currently only the "password"
   104  authentication method is supported.
   105  
   106  	config := &ClientConfig{
   107  		User: "username",
   108  		Auth: []ClientAuth{ ... },
   109  	}
   110  	client, err := Dial("yourserver.com:22", config)
   111  
   112  Each ClientConn can support multiple interactive sessions, represented by a Session.
   113  
   114  	session, err := client.NewSession()
   115  
   116  Once a Session is created, you can execute a single command on the remote side
   117  using the Exec method.
   118  
   119  	b := bytes.NewBuffer()
   120  	session.Stdin = b
   121  	if err := session.Run("/usr/bin/whoami"); err != nil {
   122  		panic("Failed to exec: " + err.String())
   123  	}
   124  	fmt.Println(bytes.String())
   125  	session.Close()
   126  */
   127  package ssh