net-ssh-backports 6.3.0.backports

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

@@ -0,0 +1,173 @@
+require 'net/ssh/buffer'
+require 'net/ssh/packet'
+require 'net/ssh/buffered_io'
+require 'net/ssh/connection/channel'
+require 'net/ssh/connection/constants'
+require 'net/ssh/transport/constants'
+require 'net/ssh/transport/packet_stream'
+
+module Net
+  module SSH
+    module Test
+      # A collection of modules used to extend/override the default behavior of
+      # Net::SSH internals for ease of testing. As a consumer of Net::SSH, you'll
+      # never need to use this directly--they're all used under the covers by
+      # the Net::SSH::Test system.
+      module Extensions
+        # An extension to Net::SSH::BufferedIo (assumes that the underlying IO
+        # is actually a StringIO). Facilitates unit testing.
+        module BufferedIo
+          # Returns +true+ if the position in the stream is less than the total
+          # length of the stream.
+          def select_for_read?
+            pos < size
+          end
+
+          # Set this to +true+ if you want the IO to pretend to be available for writing
+          attr_accessor :select_for_write
+
+          # Set this to +true+ if you want the IO to pretend to be in an error state
+          attr_accessor :select_for_error
+
+          alias select_for_write? select_for_write
+          alias select_for_error? select_for_error
+        end
+
+        # An extension to Net::SSH::Transport::PacketStream (assumes that the
+        # underlying IO is actually a StringIO). Facilitates unit testing.
+        module PacketStream
+          include BufferedIo # make sure we get the extensions here, too
+
+          def self.included(base) #:nodoc:
+            base.send :alias_method, :real_available_for_read?, :available_for_read?
+            base.send :alias_method, :available_for_read?, :test_available_for_read?
+
+            base.send :alias_method, :real_enqueue_packet, :enqueue_packet
+            base.send :alias_method, :enqueue_packet, :test_enqueue_packet
+
+            base.send :alias_method, :real_poll_next_packet, :poll_next_packet
+            base.send :alias_method, :poll_next_packet, :test_poll_next_packet
+          end
+
+          # Called when another packet should be inspected from the current
+          # script. If the next packet is a remote packet, it pops it off the
+          # script and shoves it onto this IO object, making it available to
+          # be read.
+          def idle!
+            return false unless script.next(:first)
+
+            if script.next(:first).remote?
+              self.string << script.next.to_s
+              self.pos = pos
+            end
+
+            return true
+          end
+
+          # The testing version of Net::SSH::Transport::PacketStream#available_for_read?.
+          # Returns true if there is data pending to be read. Otherwise calls #idle!.
+          def test_available_for_read?
+            return true if select_for_read?
+
+            idle!
+            false
+          end
+
+          # The testing version of Net::SSH::Transport::PacketStream#enqueued_packet.
+          # Simply calls Net::SSH::Test::Script#process on the packet.
+          def test_enqueue_packet(payload)
+            packet = Net::SSH::Buffer.new(payload.to_s)
+            script.process(packet)
+          end
+
+          # The testing version of Net::SSH::Transport::PacketStream#poll_next_packet.
+          # Reads the next available packet from the IO object and returns it.
+          def test_poll_next_packet
+            return nil if available <= 0
+
+            packet = Net::SSH::Buffer.new(read_available(4))
+            length = packet.read_long
+            Net::SSH::Packet.new(read_available(length))
+          end
+        end
+
+        # An extension to Net::SSH::Connection::Channel. Facilitates unit testing.
+        module Channel
+          def self.included(base) #:nodoc:
+            base.send :alias_method, :send_data_for_real, :send_data
+            base.send :alias_method, :send_data, :send_data_for_test
+          end
+
+          # The testing version of Net::SSH::Connection::Channel#send_data. Calls
+          # the original implementation, and then immediately enqueues the data for
+          # output so that scripted sends are properly interpreted as discrete
+          # (rather than concatenated) data packets.
+          def send_data_for_test(data)
+            send_data_for_real(data)
+            enqueue_pending_output
+          end
+        end
+
+        # An extension to the built-in ::IO class. Simply redefines IO.select
+        # so that it can be scripted in Net::SSH unit tests.
+        module IO
+          def self.included(base) #:nodoc:
+            base.extend(ClassMethods)
+          end
+
+          @extension_enabled = false
+
+          def self.with_test_extension(&block)
+            orig_value = @extension_enabled
+            @extension_enabled = true
+            begin
+              yield
+            ensure
+              @extension_enabled = orig_value
+            end
+          end
+
+          def self.extension_enabled?
+            @extension_enabled
+          end
+
+          module ClassMethods
+            def self.extended(obj) #:nodoc:
+              class <<obj
+                alias_method :select_for_real, :select
+                alias_method :select, :select_for_test
+              end
+            end
+
+            # The testing version of ::IO.select. Assumes that all readers,
+            # writers, and errors arrays are either nil, or contain only objects
+            # that mix in Net::SSH::Test::Extensions::BufferedIo.
+            def select_for_test(readers=nil, writers=nil, errors=nil, wait=nil)
+              return select_for_real(readers, writers, errors, wait) unless Net::SSH::Test::Extensions::IO.extension_enabled?
+
+              ready_readers = Array(readers).select { |r| r.select_for_read? }
+              ready_writers = Array(writers).select { |r| r.select_for_write? }
+              ready_errors  = Array(errors).select  { |r| r.select_for_error? }
+
+              return [ready_readers, ready_writers, ready_errors] if ready_readers.any? || ready_writers.any? || ready_errors.any?
+
+              processed = 0
+              Array(readers).each do |reader|
+                processed += 1 if reader.idle!
+              end
+
+              raise "no readers were ready for reading, and none had any incoming packets" if processed == 0 && wait != 0
+
+              [[], [], []]
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Net::SSH::BufferedIo.send(:include, Net::SSH::Test::Extensions::BufferedIo)
+Net::SSH::Transport::PacketStream.send(:include, Net::SSH::Test::Extensions::PacketStream)
+Net::SSH::Connection::Channel.send(:include, Net::SSH::Test::Extensions::Channel)
+IO.send(:include, Net::SSH::Test::Extensions::IO)

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

@@ -0,0 +1,46 @@
+require 'openssl'
+
+require 'net/ssh/errors'
+require 'net/ssh/transport/algorithms'
+require 'net/ssh/transport/constants'
+require 'net/ssh/transport/kex'
+
+module Net
+  module SSH
+    module Test
+      # An implementation of a key-exchange strategy specifically for unit tests.
+      # (This strategy would never really work against a real SSH server--it makes
+      # too many assumptions about the server's response.)
+      #
+      # This registers itself with the transport key-exchange system as the
+      # "test" algorithm.
+      class Kex
+        include Net::SSH::Transport::Constants
+
+        # Creates a new instance of the testing key-exchange algorithm with the
+        # given arguments.
+        def initialize(algorithms, connection, data)
+          @connection = connection
+        end
+
+        # Exchange keys with the server. This returns a hash of constant values,
+        # and does not actually exchange keys.
+        def exchange_keys
+          result = Net::SSH::Buffer.from(:byte, NEWKEYS)
+          @connection.send_message(result)
+
+          buffer = @connection.next_message
+          raise Net::SSH::Exception, "expected NEWKEYS" unless buffer.type == NEWKEYS
+
+          { session_id: "abc-xyz",
+            server_key: OpenSSL::PKey::RSA.new(512),
+            shared_secret: OpenSSL::BN.new("1234567890", 10),
+            hashing_algorithm: OpenSSL::Digest::SHA1 }
+        end
+      end
+    end
+  end
+end
+
+Net::SSH::Transport::Algorithms::ALGORITHMS[:kex] << "test"
+Net::SSH::Transport::Kex::MAP["test"] = Net::SSH::Test::Kex

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

@@ -0,0 +1,53 @@
+require 'net/ssh/packet'
+require 'net/ssh/test/packet'
+
+module Net
+  module SSH
+    module Test
+      # This is a specialization of Net::SSH::Test::Packet for representing mock
+      # packets that are sent from the local (client) host. These are created
+      # automatically by Net::SSH::Test::Script and Net::SSH::Test::Channel by any
+      # of the sends_* methods.
+      class LocalPacket < Packet
+        attr_reader :init
+
+        # Extend the default Net::SSH::Test::Packet constructor to also accept an
+        # optional block, which is used to finalize the initialization of the
+        # packet when #process is first called.
+        def initialize(type, *args, &block)
+          super(type, *args)
+          @init = block
+        end
+
+        # Returns +true+; this is a local packet.
+        def local?
+          true
+        end
+
+        # Called by Net::SSH::Test::Extensions::PacketStream#test_enqueue_packet
+        # to mimic remote processing of a locally-sent packet. It compares the
+        # packet it was given with the contents of this LocalPacket's data, to see
+        # if what was sent matches what was scripted. If it differs in any way,
+        # an exception is raised.
+        def process(packet)
+          @init.call(Net::SSH::Packet.new(packet.to_s)) if @init
+          type = packet.read_byte
+          raise "expected #{@type}, but got #{type}" if @type != type
+
+          @data.zip(types).each do |expected, _type|
+            _type ||= case expected
+                      when nil then break
+                      when Numeric then :long
+                      when String then :string
+                      when TrueClass, FalseClass then :bool
+                      end
+
+            actual = packet.send("read_#{_type}")
+            next if expected.nil?
+            raise "expected #{_type} #{expected.inspect} but got #{actual.inspect}" unless expected == actual
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+require 'net/ssh/connection/constants'
+require 'net/ssh/transport/constants'
+
+module Net
+  module SSH
+    module Test
+      # This is an abstract class, not to be instantiated directly, subclassed by
+      # Net::SSH::Test::LocalPacket and Net::SSH::Test::RemotePacket. It implements
+      # functionality common to those subclasses.
+      #
+      # These packets are not true packets, in that they don't represent what was
+      # actually sent between the hosst; rather, they represent what was expected
+      # to be sent, as dictated by the script (Net::SSH::Test::Script). Thus,
+      # though they are defined with data elements, these data elements are used
+      # to either validate data that was sent by the local host (Net::SSH::Test::LocalPacket)
+      # or to mimic the sending of data by the remote host (Net::SSH::Test::RemotePacket).
+      class Packet
+        include Net::SSH::Transport::Constants
+        include Net::SSH::Connection::Constants
+
+        # Register a custom channel request. extra_parts is an array of types
+        # of extra parameters
+        def self.register_channel_request(request, extra_parts)
+          @registered_requests ||= {}
+          @registered_requests[request] = { extra_parts: extra_parts }
+        end
+
+        def self.registered_channel_requests(request)
+          @registered_requests && @registered_requests[request]
+        end
+
+        # Ceate a new packet of the given +type+, and with +args+ being a list of
+        # data elements in the order expected for packets of the given +type+
+        # (see #types).
+        def initialize(type, *args)
+          @type = self.class.const_get(type.to_s.upcase)
+          @data = args
+        end
+
+        # The default for +remote?+ is false. Subclasses should override as necessary.
+        def remote?
+          false
+        end
+
+        # The default for +local?+ is false. Subclasses should override as necessary.
+        def local?
+          false
+        end
+
+        # Instantiates the packets data elements. When the packet was first defined,
+        # some elements may not have been fully realized, and were described as
+        # Proc objects rather than atomic types. This invokes those Proc objects
+        # and replaces them with their returned values. This allows for values
+        # like Net::SSH::Test::Channel#remote_id to be used in scripts before
+        # the remote_id is known (since it is only known after a channel has been
+        # confirmed open).
+        def instantiate!
+          @data.map! { |i| i.respond_to?(:call) ? i.call : i }
+        end
+
+        # Returns an array of symbols describing the data elements for packets of
+        # the same type as this packet. These types are used to either validate
+        # sent packets (Net::SSH::Test::LocalPacket) or build received packets
+        # (Net::SSH::Test::RemotePacket).
+        #
+        # Not all packet types are defined here. As new packet types are required
+        # (e.g., a unit test needs to test that the remote host sent a packet that
+        # is not implemented here), the description of that packet should be
+        # added. Unsupported packet types will otherwise raise an exception.
+        def types
+          @types ||= case @type
+                     when KEXINIT
+                       %i[long long long long
+                          string string string string string string string string string string
+                          bool]
+                     when NEWKEYS then []
+                     when CHANNEL_OPEN then %i[string long long long]
+                     when CHANNEL_OPEN_CONFIRMATION then %i[long long long long]
+                     when CHANNEL_DATA then %i[long string]
+                     when CHANNEL_EXTENDED_DATA then %i[long long string]
+                     when CHANNEL_EOF, CHANNEL_CLOSE, CHANNEL_SUCCESS, CHANNEL_FAILURE then [:long]
+                     when CHANNEL_REQUEST
+                       parts = %i[long string bool]
+                       case @data[1]
+                       when "exec", "subsystem","shell" then parts << :string
+                       when "exit-status" then parts << :long
+                       when "pty-req" then parts.concat(%i[string long long long long string])
+                       when "env" then parts.contact(%i[string string])
+                       else
+                         request = Packet.registered_channel_requests(@data[1])
+                         raise "don't know what to do about #{@data[1]} channel request" unless request
+
+                         parts.concat(request[:extra_parts])
+                       end
+                     else raise "don't know how to parse packet type #{@type}"
+                     end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require 'net/ssh/buffer'
+require 'net/ssh/test/packet'
+
+module Net
+  module SSH
+    module Test
+      # This is a specialization of Net::SSH::Test::Packet for representing mock
+      # packets that are received by the local (client) host. These are created
+      # automatically by Net::SSH::Test::Script and Net::SSH::Test::Channel by any
+      # of the gets_* methods.
+      class RemotePacket < Packet
+        # Returns +true+; this is a remote packet.
+        def remote?
+          true
+        end
+
+        # The #process method should only be called on Net::SSH::Test::LocalPacket
+        # packets; if it is attempted on a remote packet, then it is an expectation
+        # mismatch (a remote packet was received when a local packet was expected
+        # to be sent). This will happen when either your test script
+        # (Net::SSH::Test::Script) or your program are wrong.
+        def process(packet)
+          raise "received packet type #{packet.read_byte} and was not expecting any packet"
+        end
+
+        # Returns this remote packet as a string, suitable for parsing by
+        # Net::SSH::Transport::PacketStream and friends. When a remote packet is
+        # received, this method is called and the result concatenated onto the
+        # input buffer for the packet stream.
+        def to_s
+          @to_s ||= begin
+            instantiate!
+            string = Net::SSH::Buffer.from(:byte, @type, *types.zip(@data).flatten).to_s
+            [string.length, string].pack("NA*")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+require 'net/ssh/test/channel'
+require 'net/ssh/test/local_packet'
+require 'net/ssh/test/remote_packet'
+
+module Net
+  module SSH
+    module Test
+      # Represents a sequence of scripted events that identify the behavior that
+      # a test expects. Methods named "sends_*" create events for packets being
+      # sent from the local to the remote host, and methods named "gets_*" create
+      # events for packets being received by the local from the remote host.
+      #
+      # A reference to a script. is generally obtained in a unit test via the
+      # Net::SSH::Test#story helper method:
+      #
+      #   story do |script|
+      #     channel = script.opens_channel
+      #     ...
+      #   end
+      class Script
+        # The list of scripted events. These will be Net::SSH::Test::LocalPacket
+        # and Net::SSH::Test::RemotePacket instances.
+        attr_reader :events
+
+        # Create a new, empty script.
+        def initialize
+          @events = []
+        end
+
+        # Scripts the opening of a channel by adding a local packet sending the
+        # channel open request, and if +confirm+ is true (the default), also
+        # adding a remote packet confirming the new channel.
+        #
+        # A new Net::SSH::Test::Channel instance is returned, which can be used
+        # to script additional channel operations.
+        def opens_channel(confirm=true)
+          channel = Channel.new(self)
+          channel.remote_id = 5555
+
+          events << LocalPacket.new(:channel_open) { |p| channel.local_id = p[:remote_id] }
+
+          events << RemotePacket.new(:channel_open_confirmation, channel.local_id, channel.remote_id, 0x20000, 0x10000) if confirm
+
+          channel
+        end
+
+        # A convenience method for adding an arbitrary local packet to the events
+        # list.
+        def sends(type, *args, &block)
+          events << LocalPacket.new(type, *args, &block)
+        end
+
+        # A convenience method for adding an arbitrary remote packet to the events
+        # list.
+        def gets(type, *args)
+          events << RemotePacket.new(type, *args)
+        end
+
+        # Scripts the sending of a new channel request packet to the remote host.
+        # +channel+ should be an instance of Net::SSH::Test::Channel. +request+
+        # is a string naming the request type to send, +reply+ is a boolean
+        # indicating whether a response to this packet is required , and +data+
+        # is any additional request-specific data that this packet should send.
+        # +success+ indicates whether the response (if one is required) should be
+        # success or failure. If +data+ is an array it will be treated as multiple
+        # data.
+        #
+        # If a reply is desired, a remote packet will also be queued, :channel_success
+        # if +success+ is true, or :channel_failure if +success+ is false.
+        #
+        # This will typically be called via Net::SSH::Test::Channel#sends_exec or
+        # Net::SSH::Test::Channel#sends_subsystem.
+        def sends_channel_request(channel, request, reply, data, success=true)
+          if data.is_a? Array
+            events << LocalPacket.new(:channel_request, channel.remote_id, request, reply, *data)
+          else
+            events << LocalPacket.new(:channel_request, channel.remote_id, request, reply, data)
+          end
+          if reply
+            if success
+              events << RemotePacket.new(:channel_success, channel.local_id)
+            else
+              events << RemotePacket.new(:channel_failure, channel.local_id)
+            end
+          end
+        end
+
+        # Scripts the sending of a channel data packet. +channel+ must be a
+        # Net::SSH::Test::Channel object, and +data+ is the (string) data to
+        # expect will be sent.
+        #
+        # This will typically be called via Net::SSH::Test::Channel#sends_data.
+        def sends_channel_data(channel, data)
+          events << LocalPacket.new(:channel_data, channel.remote_id, data)
+        end
+
+        # Scripts the sending of a channel EOF packet from the given
+        # Net::SSH::Test::Channel +channel+. This will typically be called via
+        # Net::SSH::Test::Channel#sends_eof.
+        def sends_channel_eof(channel)
+          events << LocalPacket.new(:channel_eof, channel.remote_id)
+        end
+
+        # Scripts the sending of a channel close packet from the given
+        # Net::SSH::Test::Channel +channel+. This will typically be called via
+        # Net::SSH::Test::Channel#sends_close.
+        def sends_channel_close(channel)
+          events << LocalPacket.new(:channel_close, channel.remote_id)
+        end
+
+        # Scripts the sending of a channel request pty packets from the given
+        # Net::SSH::Test::Channel +channel+. This will typically be called via
+        # Net::SSH::Test::Channel#sends_request_pty.
+        def sends_channel_request_pty(channel)
+          data = ['pty-req', false]
+          data += Net::SSH::Connection::Channel::VALID_PTY_OPTIONS.merge(modes: "\0").values
+          events << LocalPacket.new(:channel_request, channel.remote_id, *data)
+        end
+
+        # Scripts the reception of a channel data packet from the remote host by
+        # the given Net::SSH::Test::Channel +channel+. This will typically be
+        # called via Net::SSH::Test::Channel#gets_data.
+        def gets_channel_data(channel, data)
+          events << RemotePacket.new(:channel_data, channel.local_id, data)
+        end
+
+        # Scripts the reception of a channel extended data packet from the remote
+        # host by the given Net::SSH::Test::Channel +channel+. This will typically
+        # be called via Net::SSH::Test::Channel#gets_extended_data.
+        #
+        # Currently the only extended data type is stderr == 1.
+        def gets_channel_extended_data(channel, data)
+          events << RemotePacket.new(:channel_extended_data, channel.local_id, 1, data)
+        end
+
+        # Scripts the reception of a channel request packet from the remote host by
+        # the given Net::SSH::Test::Channel +channel+. This will typically be
+        # called via Net::SSH::Test::Channel#gets_exit_status.
+        def gets_channel_request(channel, request, reply, data)
+          events << RemotePacket.new(:channel_request, channel.local_id, request, reply, data)
+        end
+
+        # Scripts the reception of a channel EOF packet from the remote host by
+        # the given Net::SSH::Test::Channel +channel+. This will typically be
+        # called via Net::SSH::Test::Channel#gets_eof.
+        def gets_channel_eof(channel)
+          events << RemotePacket.new(:channel_eof, channel.local_id)
+        end
+
+        # Scripts the reception of a channel close packet from the remote host by
+        # the given Net::SSH::Test::Channel +channel+. This will typically be
+        # called via Net::SSH::Test::Channel#gets_close.
+        def gets_channel_close(channel)
+          events << RemotePacket.new(:channel_close, channel.local_id)
+        end
+
+        # By default, removes the next event in the list and returns it. However,
+        # this can also be used to non-destructively peek at the next event in the
+        # list, by passing :first as the argument.
+        #
+        #   # remove the next event and return it
+        #   event = script.next
+        #
+        #   # peek at the next event
+        #   event = script.next(:first)
+        def next(mode=:shift)
+          events.send(mode)
+        end
+
+        # Compare the given packet against the next event in the list. If there is
+        # no next event, an exception will be raised. This is called by
+        # Net::SSH::Test::Extensions::PacketStream#test_enqueue_packet.
+        def process(packet)
+          event = events.shift or raise "end of script reached, but got a packet type #{packet.read_byte}"
+          event.process(packet)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+require 'socket'
+require 'stringio'
+require 'net/ssh/test/extensions'
+require 'net/ssh/test/script'
+
+module Net
+  module SSH
+    module Test
+      # A mock socket implementation for use in testing. It implements the minimum
+      # necessary interface for interacting with the rest of the Net::SSH::Test
+      # system.
+      class Socket < StringIO
+        attr_reader :host, :port
+
+        # The Net::SSH::Test::Script object in use by this socket. This is the
+        # canonical script instance that should be used for any test depending on
+        # this socket instance.
+        attr_reader :script
+
+        # Create a new test socket. This will also instantiate a new Net::SSH::Test::Script
+        # and seed it with the necessary events to power the initialization of the
+        # connection.
+        def initialize
+          extend(Net::SSH::Transport::PacketStream)
+          super "SSH-2.0-Test\r\n"
+
+          @script = Script.new
+
+          script.sends(:kexinit)
+          script.gets(:kexinit, 1, 2, 3, 4, "test", "ssh-rsa", "none", "none", "none", "none", "none", "none", "", "", false)
+          script.sends(:newkeys)
+          script.gets(:newkeys)
+        end
+
+        # This doesn't actually do anything, since we don't really care what gets
+        # written.
+        def write(data)
+          # black hole, because we don't actually care about what gets written
+        end
+
+        # Allows the socket to also mimic a socket factory, simply returning
+        # +self+.
+        def open(host, port, options={})
+          @host, @port = host, port
+          self
+        end
+
+        # Returns a sockaddr struct for the port and host that were used when the
+        # socket was instantiated.
+        def getpeername
+          ::Socket.sockaddr_in(port, host)
+        end
+
+        # Alias to #read, but never returns nil (returns an empty string instead).
+        def recv(n)
+          read(n) || ""
+        end
+
+        def readpartial(n)
+          recv(n)
+        end
+      end
+    end
+  end
+end