channel.rb

# -*- coding: binary -*-

require 'rex/post/meterpreter/inbound_packet_handler'

module Rex
module Post
module Meterpreter

#
# The various types of channels
#
CHANNEL_CLASS_STREAM     = 1
CHANNEL_CLASS_DATAGRAM   = 2
CHANNEL_CLASS_POOL       = 3

#
# The various flags that can affect how the channel operates
#
#   CHANNEL_FLAG_SYNCHRONOUS
#      Specifies that I/O requests on the channel are blocking.
#
#   CHANNEL_FLAG_COMPRESS
#      Specifies that I/O requests on the channel have their data zlib compressed.
#
CHANNEL_FLAG_SYNCHRONOUS = (1 << 0)
CHANNEL_FLAG_COMPRESS    = (1 << 1)

#
# The core types of direct I/O requests
#
CHANNEL_DIO_READ         = 'read'
CHANNEL_DIO_WRITE        = 'write'
CHANNEL_DIO_CLOSE        = 'close'

###
#
# The channel class represents a logical data pipe that exists between the
# client and the server.  The purpose and behavior of the channel depends on
# which type it is.  The three basic types of channels are streams, datagrams,
# and pools.  Streams are basically equivalent to a TCP connection.
# Bidirectional, connection-oriented streams.  Datagrams are basically
# equivalent to a UDP session.  Bidirectional, connectionless.  Pools are
# basically equivalent to a uni-directional connection, like a file handle.
# Pools denote channels that only have requests flowing in one direction.
#
###
class Channel
  # Class modifications to support global channel message
  # dispatching without having to register a per-instance handler
  class << self
    include Rex::Post::Meterpreter::InboundPacketHandler

    # Class request handler for all channels that dispatches requests
    # to the appropriate class instance's DIO handler
    def request_handler(client, packet)
      cid = packet.get_tlv_value(TLV_TYPE_CHANNEL_ID)

      # No channel identifier, then drop it
      if cid.nil?
        return false
      end

      channel = client.find_channel(cid)

      # No valid channel context? The channel may not be registered yet
      if channel.nil?
        return false
      end


      dio = channel.dio_map(packet.method)

      # Supported DIO request? Dump it.
      if dio.nil?
        return true
      end


      # Call the channel's dio handler and return success or fail
      # based on what happens
      channel.dio_handler(dio, packet)
    end
  end

  ##
  #
  # Factory
  #
  ##

  #
  # Creates a logical channel between the client and the server
  # based on a given type.
  #
  def Channel.create(client, type = nil, klass = nil,
      flags = CHANNEL_FLAG_SYNCHRONOUS, addends = nil, **klass_kwargs)
    request = Packet.create_request(COMMAND_ID_CORE_CHANNEL_OPEN)

    # Set the type of channel that we're allocating
    if !type.nil?
      request.add_tlv(TLV_TYPE_CHANNEL_TYPE, type)
    end

    # If no factory class was provided, use the default native class
    if klass.nil?
      klass = self
    end

    request.add_tlv(TLV_TYPE_CHANNEL_CLASS, klass.cls)
    request.add_tlv(TLV_TYPE_FLAGS, flags)
    request.add_tlvs(addends)

    # Transmit the request and wait for the response
    cid = nil
    begin
      response = client.send_request(request)
      cid = response.get_tlv_value(TLV_TYPE_CHANNEL_ID)
      if cid.nil?
        raise Rex::Post::Meterpreter::RequestError
      end
    end

    # Create the channel instance
    klass.new(client, cid, type, flags, response, **klass_kwargs)
  end

  ##
  #
  # Constructor
  #
  ##

  #
  # Initializes the instance's attributes, such as client context,
  # class identifier, type, and flags.
  #
  def initialize(client, cid, type, flags, packet, **_)
    self.client = client
    self.cid    = cid
    self.type   = type
    self.flags  = flags
    @mutex  = Mutex.new

    # Add this instance to the list
    if (cid and client)
      client.add_channel(self)
    end

    # Ensure the remote object is closed when all references are removed
    ObjectSpace.define_finalizer(self, self.class.finalize(client, cid))
  end

  def self.finalize(client, cid)
    proc {
      unless cid.nil?
        deferred_close_proc = proc do
          begin
            self._close(client, cid)
          rescue => e
            elog("finalize method for Channel failed", error: e)
          end
        end

        # Schedule the finalizing logic out-of-band; as this logic might be called in the context of a Signal.trap, which can't synchronize mutexes
        client.framework.sessions.schedule(deferred_close_proc)
      end
    }
  end


  ##
  #
  # Channel interaction
  #
  ##

  #
  # Wrapper around the low-level channel read operation.
  #
  def read(length = nil, addends = nil)
    return _read(length, addends)
  end

  #
  # Reads data from the remote half of the channel.
  #
  def _read(length = nil, addends = nil)
    if self.cid.nil?
      raise IOError, "Channel has been closed.", caller
    end

    request = Packet.create_request(COMMAND_ID_CORE_CHANNEL_READ)

    if length.nil?
      # Default block size to a higher amount for passive dispatcher
      length = self.client.passive_service ? (1024*1024) : 65536
    end

    request.add_tlv(TLV_TYPE_CHANNEL_ID, self.cid)
    request.add_tlv(TLV_TYPE_LENGTH, length)
    request.add_tlvs(addends)

    begin
      response = self.client.send_request(request)
    rescue
      return nil
    end

    # If the channel is in synchronous mode, the response should contain
    # data that was read from the remote side of the channel
    if (flag?(CHANNEL_FLAG_SYNCHRONOUS))
      data = response.get_tlv(TLV_TYPE_CHANNEL_DATA);

      if (data != nil)
        return data.value
      end
    else
      raise NotImplementedError, "Asynchronous channel mode is not implemented", caller
    end

    return nil
  end

  #
  # Wrapper around the low-level write.
  #
  def write(buf, length = nil, addends = nil)
    return _write(buf, length, addends)
  end

  #
  # Writes data to the remote half of the channel.
  #
  def _write(buf, length = nil, addends = nil)
    if self.cid.nil?
      raise IOError, "Channel has been closed.", caller
    end

    request = Packet.create_request(COMMAND_ID_CORE_CHANNEL_WRITE)

    # Truncation and celebration
    if ((length != nil) &&
        (buf.length >= length))
      buf = buf[0..length]
    else
      length = buf.length
    end

    # Populate the request
    request.add_tlv(TLV_TYPE_CHANNEL_ID, self.cid)

    cdata = request.add_tlv(TLV_TYPE_CHANNEL_DATA, buf)
    if( ( self.flags & CHANNEL_FLAG_COMPRESS ) == CHANNEL_FLAG_COMPRESS )
      cdata.compress = true
    end

    request.add_tlv(TLV_TYPE_LENGTH, length)
    request.add_tlvs(addends)

    response = self.client.send_request(request)
    written  = response.get_tlv(TLV_TYPE_LENGTH)

    written.nil? ? 0 : written.value
  end

  #
  # Wrapper around check for self.cid
  #
  def closed?
    self.cid.nil?
  end

  #
  # Wrapper around the low-level close.
  #
  def close(addends = nil)
    return _close(addends)
  end

  #
  # Close the channel for future writes.
  #
  def close_write
    return _close
  end

  #
  # Close the channel for future reads.
  #
  def close_read
    return _close
  end

  #
  # Closes the channel.
  #
  def self._close(client, cid, addends=nil)
    if cid.nil?
      raise IOError, "Channel has been closed.", caller
    end

    request = Packet.create_request(COMMAND_ID_CORE_CHANNEL_CLOSE)

    # Populate the request
    request.add_tlv(TLV_TYPE_CHANNEL_ID, cid)
    request.add_tlvs(addends)

    client.send_request(request, nil)

    # Disassociate this channel instance
    client.remove_channel(cid)

    return true
  end

  def _close(addends = nil)
    # let the finalizer do the work behind the scenes
    @mutex.synchronize {
      unless self.cid.nil?
        ObjectSpace.undefine_finalizer(self)
        self.class._close(self.client, self.cid, addends)
        self.cid = nil
      end
    }
  end
  #
  # Enables or disables interactive mode.
  #
  def interactive(tf = true, addends = nil)
    if self.cid.nil?
      raise IOError, "Channel has been closed.", caller
    end

    request = Packet.create_request(COMMAND_ID_CORE_CHANNEL_INTERACT)

    # Populate the request
    request.add_tlv(TLV_TYPE_CHANNEL_ID, self.cid)
    request.add_tlv(TLV_TYPE_BOOL, tf)
    request.add_tlvs(addends)

    self.client.send_request(request)

    return true
  end

  ##
  #
  # Direct I/O
  #
  ##

  #
  # Handles dispatching I/O requests based on the request packet.
  # The default implementation does nothing with direct I/O requests.
  #
  def dio_handler(dio, packet)
    if (dio == CHANNEL_DIO_READ)
      length = packet.get_tlv_value(TLV_TYPE_LENGTH)

      return dio_read_handler(packet, length)
    elsif (dio == CHANNEL_DIO_WRITE)
      data = packet.get_tlv_value(TLV_TYPE_CHANNEL_DATA)

      return dio_write_handler(packet, data)
    elsif (dio == CHANNEL_DIO_CLOSE)
      return dio_close_handler(packet)
    end
    return false;
  end

  #
  # Stub read handler.
  #
  def dio_read_handler(packet, length)
    return true
  end

  #
  # Stub write handler.
  #
  def dio_write_handler(packet, data)
    return true
  end

  #
  # Stub close handler.
  #
  def dio_close_handler(packet)
    temp_cid = nil
    @mutex.synchronize {
      temp_cid = self.cid
      self.cid = nil
    }
    client.remove_channel(temp_cid)

    # Trap IOErrors as parts of the channel may have already been closed
    begin
      self.cleanup
    rescue IOError
    end

    return true
  end

  #
  # Maps packet request methods to DIO request identifiers on a
  # per-instance basis as other instances may add custom dio
  # handlers.
  #
  def dio_map(command_id)
    if command_id == COMMAND_ID_CORE_CHANNEL_READ
      return CHANNEL_DIO_READ
    elsif command_id == COMMAND_ID_CORE_CHANNEL_WRITE
      return CHANNEL_DIO_WRITE
    elsif command_id == COMMAND_ID_CORE_CHANNEL_CLOSE
      return CHANNEL_DIO_CLOSE
    end

    return nil
  end

  ##
  #
  # Conditionals
  #
  ##

  #
  # Checks to see if a flag is set on the instance's flags attribute.
  #
  def flag?(flag)
    return ((self.flags & flag) == flag)
  end

  #
  # Returns whether or not the channel is operating synchronously.
  #
  def synchronous?
    return (self.flags & CHANNEL_FLAG_SYNCHRONOUS)
  end

  #
  # The unique channel identifier.
  #
  attr_reader   :cid
  #
  # The type of channel.
  #
  attr_reader   :type
  #
  # The class of channel (stream, datagram, pool).
  #
  attr_reader   :cls
  #
  # Any channel-specific flag, like synchronous IO.
  #
  attr_reader   :flags
  #
  # Any channel-specific parameters.
  #
  attr_accessor :params
  #
  # The associated meterpreter client instance
  #
  attr_accessor :client
protected


  attr_writer   :cid, :type, :cls, :flags # :nodoc:

  #
  # Cleans up any lingering resources
  #
  def cleanup
  end

end

end; end; end