ddollar-net-ssh 2.0.1

data/lib/net/ssh/service/forward.rb

@@ -0,0 +1,267 @@
+require 'net/ssh/loggable'
+
+module Net; module SSH; module Service
+
+  # This class implements various port forwarding services for use by
+  # Net::SSH clients. The Forward class should never need to be instantiated
+  # directly; instead, it should be accessed via the singleton instance
+  # returned by Connection::Session#forward:
+  #
+  #   ssh.forward.local(1234, "www.capify.org", 80)
+  class Forward
+    include Loggable
+
+    # The underlying connection service instance that the port-forwarding
+    # services employ.
+    attr_reader :session
+
+    # A simple class for representing a requested remote forwarded port.
+    Remote = Struct.new(:host, :port) #:nodoc:
+
+    # Instantiates a new Forward service instance atop the given connection
+    # service session. This will register new channel open handlers to handle
+    # the specialized channels that the SSH port forwarding protocols employ.
+    def initialize(session)
+      @session = session
+      self.logger = session.logger
+      @remote_forwarded_ports = {}
+      @local_forwarded_ports = {}
+      @agent_forwarded = false
+
+      session.on_open_channel('forwarded-tcpip', &method(:forwarded_tcpip))
+      session.on_open_channel('auth-agent', &method(:auth_agent_channel))
+      session.on_open_channel('auth-agent@openssh.com', &method(:auth_agent_channel))
+    end
+
+    # Starts listening for connections on the local host, and forwards them
+    # to the specified remote host/port via the SSH connection. This method
+    # accepts either three or four arguments. When four arguments are given,
+    # they are:
+    #
+    # * the local address to bind to
+    # * the local port to listen on
+    # * the remote host to forward connections to
+    # * the port on the remote host to connect to
+    #
+    # If three arguments are given, it is as if the local bind address is
+    # "127.0.0.1", and the rest are applied as above.
+    #
+    #   ssh.forward.local(1234, "www.capify.org", 80)
+    #   ssh.forward.local("0.0.0.0", 1234, "www.capify.org", 80)
+    def local(*args)
+      if args.length < 3 || args.length > 4
+        raise ArgumentError, "expected 3 or 4 parameters, got #{args.length}"
+      end
+
+      bind_address = "127.0.0.1"
+      bind_address = args.shift if args.first.is_a?(String) && args.first =~ /\D/
+
+      local_port = args.shift.to_i
+      remote_host = args.shift
+      remote_port = args.shift.to_i
+
+      socket = TCPServer.new(bind_address, local_port)
+
+      @local_forwarded_ports[[local_port, bind_address]] = socket
+
+      session.listen_to(socket) do |socket|
+        client = socket.accept
+        debug { "received connection on #{bind_address}:#{local_port}" }
+
+        channel = session.open_channel("direct-tcpip", :string, remote_host, :long, remote_port, :string, bind_address, :long, local_port) do |channel|
+          channel.info { "direct channel established" }
+        end
+
+        prepare_client(client, channel, :local)
+  
+        channel.on_open_failed do |ch, code, description|
+          channel.error { "could not establish direct channel: #{description} (#{code})" }
+          channel[:socket].close
+        end
+      end
+    end
+
+    # Terminates an active local forwarded port. If no such forwarded port
+    # exists, this will raise an exception. Otherwise, the forwarded connection
+    # is terminated.
+    #
+    #   ssh.forward.cancel_local(1234)
+    #   ssh.forward.cancel_local(1234, "0.0.0.0")
+    def cancel_local(port, bind_address="127.0.0.1")
+      socket = @local_forwarded_ports.delete([port, bind_address])
+      socket.shutdown rescue nil
+      socket.close rescue nil
+      session.stop_listening_to(socket)
+    end
+
+    # Returns a list of all active locally forwarded ports. The returned value
+    # is an array of arrays, where each element is a two-element tuple
+    # consisting of the local port and bind address corresponding to the
+    # forwarding port.
+    def active_locals
+      @local_forwarded_ports.keys
+    end
+
+    # Requests that all connections on the given remote-port be forwarded via
+    # the local host to the given port/host. The last argument describes the
+    # bind address on the remote host, and defaults to 127.0.0.1.
+    #
+    # This method will return immediately, but the port will not actually be
+    # forwarded immediately. If the remote server is not able to begin the
+    # listener for this request, an exception will be raised asynchronously.
+    #
+    # If you want to know when the connection is active, it will show up in the
+    # #active_remotes list. If you want to block until the port is active, you
+    # could do something like this:
+    #
+    #   ssh.forward.remote(80, "www.google.com", 1234, "0.0.0.0")
+    #   ssh.loop { !ssh.forward.active_remotes.include?([1234, "0.0.0.0"]) }
+    def remote(port, host, remote_port, remote_host="127.0.0.1")
+      session.send_global_request("tcpip-forward", :string, remote_host, :long, remote_port) do |success, response|
+        if success
+          debug { "remote forward from remote #{remote_host}:#{remote_port} to #{host}:#{port} established" }
+          @remote_forwarded_ports[[remote_port, remote_host]] = Remote.new(host, port)
+        else
+          error { "remote forwarding request failed" }
+          raise Net::SSH::Exception, "remote forwarding request failed"
+        end
+      end
+    end
+
+    # an alias, for token backwards compatibility with the 1.x API
+    alias :remote_to :remote
+
+    # Requests that a remote forwarded port be cancelled. The remote forwarded
+    # port on the remote host, bound to the given address on the remote host,
+    # will be terminated, but not immediately. This method returns immediately
+    # after queueing the request to be sent to the server. If for some reason
+    # the port cannot be cancelled, an exception will be raised (asynchronously).
+    #
+    # If you want to know when the connection has been cancelled, it will no
+    # longer be present in the #active_remotes list. If you want to block until
+    # the port is no longer active, you could do something like this:
+    #
+    #   ssh.forward.cancel_remote(1234, "0.0.0.0")
+    #   ssh.loop { ssh.forward.active_remotes.include?([1234, "0.0.0.0"]) }
+    def cancel_remote(port, host="127.0.0.1")
+      session.send_global_request("cancel-tcpip-forward", :string, host, :long, port) do |success, response|
+        if success
+          @remote_forwarded_ports.delete([port, host])
+        else
+          raise Net::SSH::Exception, "could not cancel remote forward request on #{host}:#{port}"
+        end
+      end
+    end
+
+    # Returns all active forwarded remote ports. The returned value is an
+    # array of two-element tuples, where the first element is the port on the
+    # remote host and the second is the bind address.
+    def active_remotes
+      @remote_forwarded_ports.keys
+    end
+
+    # Enables SSH agent forwarding on the given channel. The forwarded agent
+    # will remain active even after the channel closes--the channel is only
+    # used as the transport for enabling the forwarded connection. You should
+    # never need to call this directly--it is called automatically the first
+    # time a session channel is opened, when the connection was created with
+    # :forward_agent set to true:
+    #
+    #    Net::SSH.start("remote.host", "me", :forwrd_agent => true) do |ssh|
+    #      ssh.open_channel do |ch|
+    #        # agent will be automatically forwarded by this point
+    #      end
+    #      ssh.loop
+    #    end
+    def agent(channel)
+      return if @agent_forwarded
+      @agent_forwarded = true
+
+      channel.send_channel_request("auth-agent-req@openssh.com") do |channel, success|
+        if success
+          debug { "authentication agent forwarding is active" }
+        else
+          channel.send_channel_request("auth-agent-req") do |channel, success|
+            if success
+              debug { "authentication agent forwarding is active" }
+            else
+              error { "could not establish forwarding of authentication agent" }
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+      # Perform setup operations that are common to all forwarded channels.
+      # +client+ is a socket, +channel+ is the channel that was just created,
+      # and +type+ is an arbitrary string describing the type of the channel.
+      def prepare_client(client, channel, type)
+        client.extend(Net::SSH::BufferedIo)
+        client.logger = logger
+
+        session.listen_to(client)
+        channel[:socket] = client
+
+        channel.on_data do |ch, data|
+          ch[:socket].enqueue(data)
+        end
+
+        channel.on_close do |ch|
+          debug { "closing #{type} forwarded channel" }
+          ch[:socket].close if !client.closed?
+          session.stop_listening_to(ch[:socket])
+        end
+
+        channel.on_process do |ch|
+          if ch[:socket].closed?
+            ch.info { "#{type} forwarded connection closed" }
+            ch.close
+          elsif ch[:socket].available > 0
+            data = ch[:socket].read_available(8192)
+            ch.debug { "read #{data.length} bytes from client, sending over #{type} forwarded connection" }
+            ch.send_data(data)
+          end
+        end
+      end
+
+      # The callback used when a new "forwarded-tcpip" channel is requested
+      # by the server.  This will open a new socket to the host/port specified
+      # when the forwarded connection was first requested.
+      def forwarded_tcpip(session, channel, packet)
+        connected_address  = packet.read_string
+        connected_port     = packet.read_long
+        originator_address = packet.read_string
+        originator_port    = packet.read_long
+
+        remote = @remote_forwarded_ports[[connected_port, connected_address]]
+
+        if remote.nil?
+          raise Net::SSH::ChannelOpenFailed.new(1, "unknown request from remote forwarded connection on #{connected_address}:#{connected_port}")
+        end
+
+        client = TCPSocket.new(remote.host, remote.port)
+        info { "connected #{connected_address}:#{connected_port} originator #{originator_address}:#{originator_port}" }
+
+        prepare_client(client, channel, :remote)
+      rescue SocketError => err
+        raise Net::SSH::ChannelOpenFailed.new(2, "could not connect to remote host (#{remote.host}:#{remote.port}): #{err.message}")
+      end
+
+      # The callback used when an auth-agent channel is requested by the server.
+      def auth_agent_channel(session, channel, packet)
+        info { "opening auth-agent channel" }
+        channel[:invisible] = true
+
+        begin
+          agent = Authentication::Agent.connect(logger)
+          prepare_client(agent.socket, channel, :agent)
+        rescue Exception => e
+          error { "attempted to connect to agent but failed: #{e.class.name} (#{e.message})" }
+          raise ChannelOpenFailure.new(2, "could not connect to authentication agent")
+        end
+      end
+  end
+
+end; end; end

data/lib/net/ssh/test.rb

@@ -0,0 +1,89 @@
+require 'net/ssh/transport/session'
+require 'net/ssh/connection/session'
+require 'net/ssh/test/kex'
+require 'net/ssh/test/socket'
+
+module Net; module SSH
+
+  # This module may be used in unit tests, for when you want to test that your
+  # SSH state machines are really doing what you expect they are doing. You will
+  # typically include this module in your unit test class, and then build a
+  # "story" of expected sends and receives:
+  #
+  #   require 'test/unit'
+  #   require 'net/ssh/test'
+  #
+  #   class MyTest < Test::Unit::TestCase
+  #     include Net::SSH::Test
+  #
+  #     def test_exec_via_channel_works
+  #       story do |session|
+  #         channel = session.opens_channel
+  #         channel.sends_exec "ls"
+  #         channel.gets_data "result of ls"
+  #         channel.gets_close
+  #         channel.sends_close
+  #       end
+  #
+  #       assert_scripted do
+  #         result = nil
+  #
+  #         connection.open_channel do |ch|
+  #           ch.exec("ls") do |success|
+  #             ch.on_data { |c, data| result = data }
+  #             ch.on_close { |c| c.close }
+  #           end
+  #         end
+  #
+  #         connection.loop
+  #         assert_equal "result of ls", result
+  #       end
+  #     end
+  #   end
+  #
+  # See Net::SSH::Test::Channel and Net::SSH::Test::Script for more options.
+  #
+  # Note that the Net::SSH::Test system is rather finicky yet, and can be kind
+  # of frustrating to get working. Any suggestions for improvement will be
+  # welcome!
+  module Test
+    # If a block is given, yields the script for the test socket (#socket).
+    # Otherwise, simply returns the socket's script. See Net::SSH::Test::Script.
+    def story
+      yield socket.script if block_given?
+      return socket.script
+    end
+
+    # Returns the test socket instance to use for these tests (see
+    # Net::SSH::Test::Socket).
+    def socket(options={})
+      @socket ||= Net::SSH::Test::Socket.new
+    end
+
+    # Returns the connection session (Net::SSH::Connection::Session) for use
+    # in these tests. It is a fully functional SSH session, operating over
+    # a mock socket (#socket).
+    def connection(options={})
+      @connection ||= Net::SSH::Connection::Session.new(transport(options), options)
+    end
+
+    # Returns the transport session (Net::SSH::Transport::Session) for use
+    # in these tests. It is a fully functional SSH transport session, operating
+    # over a mock socket (#socket).
+    def transport(options={})
+      @transport ||= Net::SSH::Transport::Session.new(options[:host] || "localhost", options.merge(:kex => "test", :host_key => "ssh-rsa", :paranoid => false, :proxy => socket(options)))
+    end
+
+    # First asserts that a story has been described (see #story). Then yields,
+    # and then asserts that all items described in the script have been
+    # processed. Typically, this is called immediately after a story has
+    # been built, and the SSH commands being tested are then executed within
+    # the block passed to this assertion.
+    def assert_scripted
+      raise "there is no script to be processed" if socket.script.events.empty?
+      yield
+      assert socket.script.events.empty?, "there should not be any remaining scripted events, but there are still #{socket.script.events.length} pending"
+    end
+  end
+
+end; end

data/lib/net/ssh/test/channel.rb

@@ -0,0 +1,129 @@
+module Net; module SSH; module Test
+
+  # A mock channel, used for scripting actions in tests. It wraps a
+  # Net::SSH::Test::Script instance, and delegates to it for the most part.
+  # This class has little real functionality on its own, but rather acts as
+  # a convenience for scripting channel-related activity for later comparison
+  # in a unit test.
+  #
+  #   story do |session|
+  #     channel = session.opens_channel
+  #     channel.sends_exec "ls"
+  #     channel.gets_data "result of ls"
+  #     channel.gets_close
+  #     channel.sends_close
+  #   end
+  class Channel
+    # The Net::SSH::Test::Script instance employed by this mock channel.
+    attr_reader :script
+
+    # Sets the local-id of this channel object (the id assigned by the client).
+    attr_writer :local_id
+
+    # Sets the remote-id of this channel object (the id assigned by the mock-server).
+    attr_writer :remote_id
+
+    # Creates a new Test::Channel instance on top of the given +script+ (which
+    # must be a Net::SSH::Test::Script instance).
+    def initialize(script)
+      @script = script
+      @local_id = @remote_id = nil
+    end
+
+    # Returns the local (client-assigned) id for this channel, or a Proc object
+    # that will return the local-id later if the local id has not yet been set.
+    # (See Net::SSH::Test::Packet#instantiate!.)
+    def local_id
+      @local_id || Proc.new { @local_id or raise "local-id has not been set yet!" }
+    end
+
+    # Returns the remote (server-assigned) id for this channel, or a Proc object
+    # that will return the remote-id later if the remote id has not yet been set.
+    # (See Net::SSH::Test::Packet#instantiate!.)
+    def remote_id
+      @remote_id || Proc.new { @remote_id or raise "remote-id has not been set yet!" }
+    end
+
+    # Because adjacent calls to #gets_data will sometimes cause the data packets
+    # to be concatenated (causing expectations in tests to fail), you may
+    # need to separate those calls with calls to #inject_remote_delay! (which
+    # essentially just mimics receiving an empty data packet):
+    #
+    #   channel.gets_data "abcdefg"
+    #   channel.inject_remote_delay!
+    #   channel.gets_data "hijklmn"
+    def inject_remote_delay!
+      gets_data("")
+    end
+
+    # Scripts the sending of an "exec" channel request packet to the mock 
+    # server. If +reply+ is true, then the server is expected to reply to the
+    # request, otherwise no response to this request will be sent. If +success+
+    # is +true+, then the request will be successful, otherwise a failure will
+    # be scripted.
+    #
+    #   channel.sends_exec "ls -l"
+    def sends_exec(command, reply=true, success=true)
+      script.sends_channel_request(self, "exec", reply, command, success)
+    end
+
+    # Scripts the sending of a "subsystem" channel request packet to the mock
+    # server. See #sends_exec for a discussion of the meaning of the +reply+
+    # and +success+ arguments.
+    #
+    #   channel.sends_subsystem "sftp"
+    def sends_subsystem(subsystem, reply=true, success=true)
+      script.sends_channel_request(self, "subsystem", reply, subsystem, success)
+    end
+
+    # Scripts the sending of a data packet across the channel.
+    #
+    #   channel.sends_data "foo"
+    def sends_data(data)
+      script.sends_channel_data(self, data)
+    end
+
+    # Scripts the sending of an EOF packet across the channel.
+    #
+    #   channel.sends_eof
+    def sends_eof
+      script.sends_channel_eof(self)
+    end
+
+    # Scripts the sending of a "channel close" packet across the channel.
+    #
+    #   channel.sends_close
+    def sends_close
+      script.sends_channel_close(self)
+    end
+
+    # Scripts the reception of a channel data packet from the remote end.
+    #
+    #   channel.gets_data "bar"
+    def gets_data(data)
+      script.gets_channel_data(self, data)
+    end
+
+    # Scripts the reception of an "exit-status" channel request packet.
+    #
+    #   channel.gets_exit_status(127)
+    def gets_exit_status(status=0)
+      script.gets_channel_request(self, "exit-status", false, status)
+    end
+
+    # Scripts the reception of an EOF packet from the remote end.
+    #
+    #   channel.gets_eof
+    def gets_eof
+      script.gets_channel_eof(self)
+    end
+
+    # Scripts the reception of a "channel close" packet from the remote end.
+    #
+    #   channel.gets_close
+    def gets_close
+      script.gets_channel_close(self)
+    end
+  end
+
+end; end; end