net-ssh 1.1.4 → 2.0.0

data/lib/net/ssh/transport/session.rb

@@ -1,340 +1,262 @@
-#--
-# =============================================================================
-# Copyright (c) 2004,2005 Jamis Buck (jamis@37signals.com)
-# All rights reserved.
-#
-# This source file is distributed as part of the Net::SSH Secure Shell Client
-# library for Ruby. This file (and the library as a whole) may be used only as
-# allowed by either the BSD license, or the Ruby license (or, by association
-# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
-# distribution for the texts of these licenses.
-# -----------------------------------------------------------------------------
-# net-ssh website : http://net-ssh.rubyforge.org
-# project website: http://rubyforge.org/projects/net-ssh
-# =============================================================================
-#++
-
 require 'socket'
 require 'timeout'
-require 'net/ssh/transport/constants'
-require 'net/ssh/transport/errors'
+
+require 'net/ssh/errors'
+require 'net/ssh/loggable'
 require 'net/ssh/version'
+require 'net/ssh/transport/algorithms'
+require 'net/ssh/transport/constants'
+require 'net/ssh/transport/packet_stream'
+require 'net/ssh/transport/server_version'
+require 'net/ssh/verifiers/null'
+require 'net/ssh/verifiers/strict'
+require 'net/ssh/verifiers/lenient'
 
-module Net
-  module SSH
-    module Transport
-
-      # Represents a low-level SSH session, at the transport protocol level.
-      # This handles the algorithm negotiation and key exchange for any SSH
-      # connection.
-      class Session
-        include Constants
-        
-        # the unique session identifier
-        attr_reader :session_id
-
-        # the collection of algorithms currently being used
-        attr_reader :algorithms
-
-        # the hostname that was requested
-        attr_reader :host
-
-        # the port that was requested
-        attr_reader :port
-
-        attr_writer :logger
-        attr_writer :default_port
-        attr_writer :version_negotiator
-        attr_writer :algorithm_negotiator
-        attr_writer :socket_factory
-        attr_writer :packet_sender
-        attr_writer :packet_receiver
-        attr_writer :ciphers
-        attr_writer :hmacs
-        attr_writer :kexs
-        attr_writer :compressors
-        attr_writer :decompressors
-
-        # The name that Net::SSH reports for itself
-        NAME = "Ruby/Net::SSH"
-
-        # The SSH protocol supported by Net::SSH.
-        PROTOCOL = "SSH-2.0"
-
-        # Returns the version string of this client.
-        def self.version
-          "#{PROTOCOL}-#{NAME}_#{Net::SSH::Version::STRING}"
-        end
+module Net; module SSH; module Transport
 
-        VALID_OPTIONS = [ :port, :host_key, :kex, :encryption, :hmac,
-                          :compression, :languages, :compression_level, :proxy,
-                          :timeout ]
+  # The transport layer represents the lowest level of the SSH protocol, and
+  # implements basic message exchanging and protocol initialization. It will
+  # never be instantiated directly (unless you really know what you're about),
+  # but will instead be created for you automatically when you create a new
+  # SSH session via Net::SSH.start.
+  class Session
+    include Constants, Loggable
 
-        # Create a new connection to the given host. This will negotiate the
-        # algorithms to use and exchange the keys. A block must be given. The
-        # uninitialized +self+ will be passed to the block, so that dependencies
-        # may be injected.
-        def initialize( host, options={} )
-          @saved_message = nil
-          @session_id = nil
-          @host = host
+    # The standard port for the SSH protocol.
+    DEFAULT_PORT = 22
 
-          yield self
+    # The host to connect to, as given to the constructor.
+    attr_reader :host
 
-          invalid_options = options.keys - VALID_OPTIONS
+    # The port number to connect to, as given in the options to the constructor.
+    # If no port number was given, this will default to DEFAULT_PORT.
+    attr_reader :port
 
-          unless invalid_options.empty?
-            raise ArgumentError,
-              "invalid option(s) to #{self.class}: #{invalid_options.inspect}"
-          end
+    # The underlying socket object being used to communicate with the remote
+    # host.
+    attr_reader :socket
 
-          @logger.debug "connecting" if @logger.debug?
+    # The ServerVersion instance that encapsulates the negotiated protocol
+    # version.
+    attr_reader :server_version
 
-          @port = options[ :port ] || @default_port
-          @socket = timeout( options[:timeout] || 0 ) do
-            ( options[:proxy] || @socket_factory ).open( host, @port )
-          end
+    # The Algorithms instance used to perform key exchanges.
+    attr_reader :algorithms
 
-          @packet_sender.socket = @socket
-          @packet_receiver.socket = @socket
+    # The host-key verifier object used to verify host keys, to ensure that
+    # the connection is not being spoofed.
+    attr_reader :host_key_verifier
 
-          @kex_info = {
-            :client_version_string => self.class.version,
-            :server_version_string =>
-              @version_negotiator.negotiate( @socket, self.class.version ) }
+    # The hash of options that were given to the object at initialization.
+    attr_reader :options
 
-          @options = options
-          kexinit
-        end
+    # Instantiates a new transport layer abstraction. This will block until
+    # the initial key exchange completes, leaving you with a ready-to-use
+    # transport session.
+    def initialize(host, options={})
+      self.logger = options[:logger]
 
-        # Returns info about the remote peer
-        def peer
-          @peer ||= begin
-            addr = @socket.getpeername
-            ip_address = Socket.getnameinfo(addr, Socket::NI_NUMERICHOST | Socket::NI_NUMERICSERV).first
-            { :ip => ip_address, :port => @port.to_i, :host => @host }
-          end
-        end
+      @host = host
+      @port = options[:port] || DEFAULT_PORT
+      @options = options
 
-        # Returns the name of the client's host, as reported by the socket.
-        def client_name
-          return @hostname if defined? @hostname
-
-          sockaddr = @socket.getsockname
-          begin
-            @hostname =
-              Socket.getnameinfo( sockaddr, Socket::NI_NAMEREQD ).first
-          rescue
-            begin
-              @hostname = Socket.getnameinfo( sockaddr ).first
-            rescue
-              begin
-                @hostname = Socket.gethostbyname( Socket.gethostname ).first
-              rescue
-                @logger.error "the client ipaddr/name could not be determined"
-              end
-            end
-          end
+      debug { "establishing connection to #{@host}:#{@port}" }
+      factory = options[:proxy] || TCPSocket
+      @socket = timeout(options[:timeout] || 0) { factory.open(@host, @port) }
+      @socket.extend(PacketStream)
+      @socket.logger = @logger
 
-          return @hostname
-        end
+      debug { "connection established" }
 
-        def kexinit
-          @doing_kexinit = true
-          @algorithms = @algorithm_negotiator.negotiate( self, @options )
+      @queue = []
 
-          @kex_info[ :server_algorithm_packet ] = @algorithms.server_packet
-          @kex_info[ :client_algorithm_packet ] = @algorithms.client_packet
+      @host_key_verifier = select_host_key_verifier(options[:paranoid])
 
-          exchange_keys
-          @doing_kexinit = false
-        end
-        private :kexinit
+      @server_version = ServerVersion.new(socket, logger)
+
+      @algorithms = Algorithms.new(self, options)
+      wait { algorithms.initialized? }
+    end
 
-        # Closes the connection.
-        def close
-          # TODO: send a DISCONNECT message to the server to close gracefully
-          @socket.close
+    # Returns the host (and possibly IP address) in a format compatible with
+    # SSH known-host files.
+    def host_as_string
+      @host_as_string ||= begin
+        string = "#{host}"
+        string = "[#{string}]:#{port}" if port != DEFAULT_PORT
+        if socket.peer_ip != host
+          string2 = socket.peer_ip
+          string2 = "[#{string2}]:#{port}" if port != DEFAULT_PORT
+          string << "," << string2
         end
+        string
+      end
+    end
 
-        def get_kex_byte_requirement
-          need = 0
+    # Cleans up (see PacketStream#cleanup) and closes the underlying socket.
+    def close
+      socket.cleanup
+      socket.close
+    end
 
-          [ @algorithms.encryption_s2c,
-            @algorithms.encryption_c2s
-          ].each do |alg|
-            key_len, block_size = @ciphers.get_lengths( alg )
-            need = key_len if need < key_len
-            need = block_size if need < block_size
-          end
+    # Returns a new service_request packet for the given service name, ready
+    # for sending to the server.
+    def service_request(service)
+      Net::SSH::Buffer.from(:byte, SERVICE_REQUEST, :string, service)
+    end
 
-          [ @algorithms.mac_c2s, @algorithms.mac_s2c ].each do |alg|
-            key_len = @hmacs.get_key_length( alg )
-            need = key_len if need < key_len
-          end
+    # Requests a rekey operation, and blocks until the operation completes.
+    # If a rekey is already pending, this returns immediately, having no
+    # effect.
+    def rekey!
+      if !algorithms.pending?
+        algorithms.rekey!
+        wait { algorithms.initialized? }
+      end
+    end
 
-          return need
-        end
-        private :get_kex_byte_requirement
-        
-        # Exchanges keys with the server, using the kex algorithm negotiated
-        # during the algorithm negotiation phase. After finishing this phase,
-        # further packets sent to or from the server will be encrypted and
-        # (possibly) compressed.
-        def exchange_keys
-          @kex_info[ :need_bytes ] = get_kex_byte_requirement
-
-          kex = @kexs.fetch( @algorithms.kex )
-          result = kex.exchange_keys( self, @kex_info )
-
-          @shared_secret = result[ :shared_secret ]
-          hash = result[ :session_id ]
-          @session_id = hash unless @session_id
-          @server_key = result[ :server_key ]
-          @hashing_algorithm = result[ :hashing_algorithm ]
-
-          # prepare the ciphers, et. al.
-          secret_bin = @shared_secret.to_ssh
-
-          iv_c2s = @hashing_algorithm.digest( secret_bin +
-                                              hash +
-                                              "A" +
-                                              @session_id )
-          iv_s2c = @hashing_algorithm.digest( secret_bin +
-                                              hash +
-                                              "B" +
-                                              @session_id )
-          key_c2s = @hashing_algorithm.digest( secret_bin +
-                                               hash +
-                                               "C" +
-                                               @session_id )
-          key_s2c = @hashing_algorithm.digest( secret_bin +
-                                               hash +
-                                               "D" +
-                                               @session_id )
-          mac_key_c2s = @hashing_algorithm.digest( secret_bin +
-                                                   hash +
-                                                   "E" +
-                                                   @session_id )
-          mac_key_s2c = @hashing_algorithm.digest( secret_bin +
-                                                   hash +
-                                                   "F" +
-                                                   @session_id )
-
-          cipher_c2s = @ciphers.get( 
-                            @algorithms.encryption_c2s, iv_c2s, key_c2s,
-                            secret_bin, hash, @hashing_algorithm,
-                            true )
-
-          cipher_s2c = @ciphers.get( 
-                            @algorithms.encryption_s2c, iv_s2c, key_s2c,
-                            secret_bin, hash, @hashing_algorithm,
-                            false )
-
-          mac_c2s = @hmacs.get( @algorithms.mac_c2s, mac_key_c2s );
-          mac_s2c = @hmacs.get( @algorithms.mac_s2c, mac_key_s2c );
-
-          compression_c2s = @compressors[ @algorithms.compression_c2s ].new(
-              :level => @algorithms.compression_level )
-          compression_s2c = @decompressors[ @algorithms.compression_s2c ].new
-
-          @packet_sender.set_algorithms cipher_c2s, mac_c2s, compression_c2s
-          @packet_receiver.set_algorithms cipher_s2c, mac_s2c, compression_s2c
-        end
-        private :exchange_keys
-
-        # Waits for the next message from the server, handling common requests
-        # like DISCONNECT, IGNORE, DEBUG, and KEXINIT in the background. The
-        # next message is returned as a [ type, buffer ] tuple, where the buffer
-        # is a Net::SSH::Util::ReaderBuffer.
-        def wait_for_message
-          buffer = type = nil
-
-          if @saved_message
-            type, buffer = @saved_message
-            @logger.debug "returning saved message: #{type}" if @logger.debug?
-            @saved_message = nil
-          else
-            loop do
-              if @logger.debug?
-                @logger.debug "waiting for packet from server..."
-              end
-
-              buffer = @packet_receiver.get
-              next unless buffer
-
-              type = buffer.read_byte
-              @logger.debug "got packet of type #{type}" if @logger.debug?
-
-              case type
-                when DISCONNECT
-                  reason_code = buffer.read_long
-                  description = buffer.read_string
-                  language = buffer.read_string
-                  raise Net::SSH::Transport::Disconnect,
-                    "disconnected: #{description} (#{reason_code})"
-
-                when IGNORE
-                  # do nothing
-                  @logger.info "received IGNORE message " +
-                    "(#{buffer.read_string.inspect})" if @logger.debug?
-
-                when DEBUG
-                  # do nothing
-                  @logger.info "received DEBUG message" if @logger.debug?
-                  always_display = buffer.read_bool
-                  message = buffer.read_string
-                  language = buffer.read_string
-                  if always_display
-                    @logger.warn "#{message} (#{language})" if @logger.warn?
-                  else
-                    @logger.debug "#{message} (#{language})" if @logger.debug?
-                  end
-
-                when KEXINIT
-                  # unless we're already doing a key-exchange, do key
-                  # re-exchange
-                  if !@doing_kexinit
-                    @logger.info "re-key requested" if @logger.info?
-                    @saved_message = [ type, buffer ]
-                    kexinit
-                  else
-                    break
-                  end
-
-                else
-                  break
-              end
-            end
-          end
+    # Returns immediately if a rekey is already in process. Otherwise, if a
+    # rekey is needed (as indicated by the socket, see PacketStream#if_needs_rekey?)
+    # one is performed, causing this method to block until it completes.
+    def rekey_as_needed
+      return if algorithms.pending?
+      socket.if_needs_rekey? { rekey! }
+    end
 
-          return type, buffer
-        end
+    # Returns a hash of information about the peer (remote) side of the socket,
+    # including :ip, :port, :host, and :canonized (see #host_as_string).
+    def peer
+      @peer ||= { :ip => socket.peer_ip, :port => @port.to_i, :host => @host, :canonized => host_as_string }
+    end
 
-        # Sends the given payload, using the currently configured
-        # OutgoingPacketStream.
-        def send_message( message )
-          if @logger.debug?
-            @logger.debug "sending message >>#{message.to_s.inspect}<<"
-          end
+    # Blocks until a new packet is available to be read, and returns that
+    # packet. See #poll_message.
+    def next_message
+      poll_message(:block)
+    end
 
-          @packet_sender.send message
+    # Tries to read the next packet from the socket. If mode is :nonblock (the
+    # default), this will not block and will return nil if there are no packets
+    # waiting to be read. Otherwise, this will block until a packet is
+    # available. Note that some packet types (DISCONNECT, IGNORE, UNIMPLEMENTED,
+    # DEBUG, and KEXINIT) are handled silently by this method, and will never
+    # be returned.
+    #
+    # If a key-exchange is in process and a disallowed packet type is
+    # received, it will be enqueued and otherwise ignored. When a key-exchange
+    # is not in process, and consume_queue is true, packets will be first
+    # read from the queue before the socket is queried.
+    def poll_message(mode=:nonblock, consume_queue=true)
+      loop do
+        if consume_queue && @queue.any? && algorithms.allow?(@queue.first)
+          return @queue.shift
         end
 
-        # Returns true if there are bytes to be read on the socket. Note that
-        # this only means there is an encrypted packet ready to be read, not
-        # that there is data available to any particular SSH channel.
-        def reader_ready?
-          IO.select([@socket],nil,nil,0) != nil
-        end
+        packet = socket.next_packet(mode)
+        return nil if packet.nil?
+
+        case packet.type
+        when DISCONNECT
+          raise Net::SSH::Disconnect, "disconnected: #{packet[:description]} (#{packet[:reason_code]})"
+
+        when IGNORE
+          debug { "IGNORE packet recieved: #{packet[:data].inspect}" }
+
+        when UNIMPLEMENTED
+          lwarn { "UNIMPLEMENTED: #{packet[:number]}" }
 
-        # Sends an IGNORE packet to the server, as a way to ping the connection
-        # and make sure the server knows the client is still active.
-        def ping!
-          send_message [IGNORE, 4, "ping"].pack("cNA4")
+        when DEBUG
+          send(packet[:always_display] ? :fatal : :debug) { packet[:message] }
+
+        when KEXINIT
+          algorithms.accept_kexinit(packet)
+
+        else
+          return packet if algorithms.allow?(packet)
+          push(packet)
         end
       end
+    end
+
+    # Waits (blocks) until the given block returns true. If no block is given,
+    # this just waits long enough to see if there are any pending packets. Any
+    # packets read are enqueued (see #push).
+    def wait
+      loop do
+        break if block_given? && yield
+        message = poll_message(:nonblock, false)
+        push(message) if message
+        break if !block_given?
+      end
+    end
+
+    # Adds the given packet to the packet queue. If the queue is non-empty,
+    # #poll_message will return packets from the queue in the order they
+    # were received.
+    def push(packet)
+      @queue.push(packet)
+    end
+
+    # Sends the given message via the packet stream, blocking until the
+    # entire message has been sent.
+    def send_message(message)
+      socket.send_packet(message)
+    end
+
+    # Enqueues the given message, such that it will be sent at the earliest
+    # opportunity. This does not block, but returns immediately.
+    def enqueue_message(message)
+      socket.enqueue_packet(message)
+    end
+
+    # Configure's the packet stream's client state with the given set of
+    # options. This is typically used to define the cipher, compression, and
+    # hmac algorithms to use when sending packets to the server.
+    def configure_client(options={})
+      socket.client.set(options)
+    end
 
+    # Configure's the packet stream's server state with the given set of
+    # options. This is typically used to define the cipher, compression, and
+    # hmac algorithms to use when reading packets from the server.
+    def configure_server(options={})
+      socket.server.set(options)
     end
+
+    # Sets a new hint for the packet stream, which the packet stream may use
+    # to change its behavior. (See PacketStream#hints).
+    def hint(which, value=true)
+      socket.hints[which] = value
+    end
+
+    public
+
+      # this method is primarily for use in tests
+      attr_reader :queue #:nodoc:
+
+    private
+
+      # Instantiates a new host-key verification class, based on the value of
+      # the parameter. When true or nil, the default Lenient verifier is
+      # returned. If it is false, the Null verifier is returned, and if it is
+      # :very, the Strict verifier is returned. If the argument happens to
+      # respond to :verify, it is returned directly. Otherwise, an exception
+      # is raised.
+      def select_host_key_verifier(paranoid)
+        case paranoid
+        when true, nil then
+          Net::SSH::Verifiers::Lenient.new
+        when false then
+          Net::SSH::Verifiers::Null.new
+        when :very then
+          Net::SSH::Verifiers::Strict.new
+        else
+          if paranoid.respond_to?(:verify)
+            paranoid
+          else
+            raise ArgumentError, "argument to :paranoid is not valid: #{paranoid.inspect}"
+          end
+        end
+      end
   end
-end
+end; end; end