net-tns 1.0.0

data/lib/net/tns/helpers/string_helpers.rb

@@ -0,0 +1,49 @@
+module Net::TNS
+  # This module includes common string helper methods for monkey-patching
+  # or mixing-in to string objects.
+  module StringHelpers
+    HEXCHARS = [("0".."9").to_a, ("a".."f").to_a].flatten
+
+    #From the Ruby Black Bag (http://github.com/emonti/rbkb/)
+    # Convert a string to ASCII hex string. Supports a few options for format:
+    #
+    # :delim - delimter between each hex byte
+    # :prefix - prefix before each hex byte
+    # :suffix - suffix after each hex byte
+    #
+    def tns_hexify(opts={})
+      delim = opts[:delim]
+      pre = (opts[:prefix] || "")
+      suf = (opts[:suffix] || "")
+
+      if (rx=opts[:rx]) and not rx.kind_of? Regexp
+        raise "rx must be a regular expression for a character class"
+      end
+
+      out=Array.new
+
+      self.each_byte do |c|
+        hc = if (rx and not rx.match c.chr)
+               c.chr
+             else
+               pre + (HEXCHARS[(c >> 4)] + HEXCHARS[(c & 0xf )]) + suf
+             end
+        out << (hc)
+      end
+      out.join(delim)
+    end
+
+    # Convert ASCII hex string to raw.
+    #
+    # Parameters:
+    #
+    #   d = optional 'delimiter' between hex bytes (zero+ spaces by default)
+    def tns_unhexify(d=/\s*/)
+      self.strip.gsub(/([A-Fa-f0-9]{1,2})#{d}?/) { $1.hex.chr }
+    end
+  end
+end
+
+class String
+  include Net::TNS::StringHelpers
+end

data/lib/net/tns/packet.rb

@@ -0,0 +1,82 @@
+require "bindata"
+
+module Net
+  module TNS
+    class Header < BinData::Record
+      LENGTH = 8
+
+      uint16be :packet_length
+      uint16be :packet_checksum
+      uint8    :packet_type
+      uint8    :flags
+      uint16be :checksum
+    end
+
+    class Packet < BinData::Record
+      SESSION_DATA_UNIT_SIZE = 2048
+      MAX_PAYLOAD_SIZE = SESSION_DATA_UNIT_SIZE - Header::LENGTH
+
+      # BinData fields
+      header :header
+
+
+      def self.register_tns_type(tns_type)
+        @@tns_packet_classes ||= {}
+        @@tns_packet_types ||= {}
+        if @@tns_packet_classes.has_key?(tns_type)
+          existing_class = @@tns_packet_classes[tns_type]
+          raise("Duplicate TNS Types Defined: #{existing_class} and #{self} both have a type of #{tns_type}")
+        end
+
+        @@tns_packet_classes[tns_type] = self
+        @@tns_packet_types[self] = tns_type
+        return nil
+      end
+
+      def self.from_socket( socket )
+        Net::TNS.logger.debug("Attempting to read header")
+        # TODO: allow sockets to implement their own timeout behavior
+        require "timeout"
+        begin
+          header_raw = Timeout::timeout(5) do
+            socket.read(Header::LENGTH)
+          end
+        rescue Timeout::Error
+          raise Exceptions::ReceiveTimeoutExceeded
+        end
+
+        if header_raw.nil? || header_raw.length != Header::LENGTH
+          raise Exceptions::ProtocolException
+        end
+
+        header = Header.new()
+        header.read( header_raw )
+        Net::TNS.logger.debug("Read header. Reported packet length is #{header.packet_length} bytes")
+        raise Exceptions::ProtocolException if header.packet_length > SESSION_DATA_UNIT_SIZE
+
+        payload_raw = socket.read( header.packet_length - Header::LENGTH )
+        packet_raw = header_raw + payload_raw
+
+        unless payload_class = @@tns_packet_classes[ header.packet_type ]
+          raise Net::TNS::Exceptions::TnsException.new( "Unknown TNS packet type: #{header.packet_type}" )
+        end
+
+        new_packet = payload_class.read( packet_raw )
+        return new_packet
+      end
+
+      def update_header()
+        self.header.packet_type = @@tns_packet_types[self.class]
+        self.header.packet_length = self.num_bytes
+      end
+
+      def to_binary_s()
+        update_header()
+        return super
+      end
+    end
+  end
+end
+
+require "pathname"
+Dir.glob("#{Pathname.new(__FILE__).dirname}/packets/*.rb") { |file| require file }

data/lib/net/tns/packets/abort_packet.rb

@@ -0,0 +1,12 @@
+module Net
+  module TNS
+    class AbortPacket < Packet
+      register_tns_type 9
+
+      uint8   :user_reason
+      uint8   :system_reason
+      # not sure if this is correct, it's just what wireshark seems to do
+      rest    :data
+    end
+  end
+end

data/lib/net/tns/packets/accept_packet.rb

@@ -0,0 +1,19 @@
+module Net
+  module TNS
+    class AcceptPacket < Packet
+      register_tns_type 2
+
+      uint16be  :version
+      uint16be  :service_flags
+      uint16be  :sdu_size         # session data unit size
+      uint16be  :maximum_tdu_size # maximum transmission data unit size
+      uint16be  :byte_order       # 0x0001 for little endian 0x0100 for big endian
+      uint16be  :data_length
+      uint16be  :data_offset      # Offset to Connect Data (from parent header start)
+      uint8     :flags1
+      uint8     :flags2
+      string    :padding, :read_length => lambda {data_offset - 24}
+      string    :data,    :read_length => :data_length
+    end
+  end
+end

data/lib/net/tns/packets/ack_packet.rb

@@ -0,0 +1,7 @@
+module Net
+  module TNS
+    class AckPacket < Packet
+      register_tns_type 3
+    end
+  end
+end

data/lib/net/tns/packets/attention_packet.rb

@@ -0,0 +1,9 @@
+module Net
+  module TNS
+    class AttentionPacket < Packet
+      register_tns_type 13
+
+      rest     :data
+    end
+  end
+end

data/lib/net/tns/packets/connect_packet.rb

@@ -0,0 +1,55 @@
+require "net/tns/version"
+
+module Net
+  module TNS
+    class ConnectPacket < Packet
+      register_tns_type 1
+
+      uint16be  :maximum_version,   :initial_value => Net::TNS::Version::VERSION_11G
+      uint16be  :minimum_version,   :initial_value => Net::TNS::Version::ALL_VERSIONS.min
+      uint16be  :service_flags
+      # session data unit size
+      uint16be  :sdu_size,          :initial_value => 0x0800
+      # maximum transmission data unit size
+      uint16be  :maximum_tdu_size,  :initial_value => 0x7fff
+      uint16be  :protocol_flags,    :initial_value => 0xc608
+      # Described as "Max packets before ACK" by http://www.pythian.com/blog/repost-oracle-protocol/
+      uint16be  :line_turnaround_value
+      # 0x0001 for little endian 0x0100 for big endian
+      uint16be  :byte_order,        :initial_value => 0x0001
+      uint16be  :data_length,       :value => lambda { data.length } # Length of Connect Data
+      uint16be  :data_offset,       :value => lambda { supports_trace? ? 58 : 34 }  # Offset to Connect Data (from start of TNS header)
+      # Maximum Receivable Connect Data
+      uint32be  :maximum_connect_receive
+      uint8     :flags1,        :initial_value => 0x41
+      uint8     :flags2,        :initial_value => 0x41
+
+      uint32be  :trace_item1,         :onlyif => :supports_trace?
+      uint32be  :trace_item2,         :onlyif => :supports_trace?
+      uint64be  :trace_connection_id, :onlyif => :supports_trace?
+      uint64be  :unknown,             :onlyif => :supports_trace?
+
+      string    :data
+
+      def self.make_connect_request(dst_host, dst_port, target_clause)
+        conn_info = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=%s)(PORT=%i))(CONNECT_DATA=(SERVER=DEDICATED)%s))" %
+                      [ dst_host, dst_port, target_clause ]
+        return self.new(:data => conn_info)
+      end
+
+      def self.make_connection_by_sid(dst_host, dst_port, sid)
+        target_clause = "(SID=#{sid})"
+        return make_connect_request(dst_host, dst_port, target_clause)
+      end
+
+      def self.make_connection_by_service_name(dst_host, dst_port, service_name)
+        target_clause = "(SERVICE_NAME=#{service_name})"
+        return make_connect_request(dst_host, dst_port, target_clause)
+      end
+
+      def supports_trace?
+        return maximum_version > 308
+      end
+    end
+  end
+end

data/lib/net/tns/packets/control_packet.rb

@@ -0,0 +1,7 @@
+module Net
+  module TNS
+    class ControlPacket < Packet
+      register_tns_type 14
+    end
+  end
+end

data/lib/net/tns/packets/data_packet.rb

@@ -0,0 +1,20 @@
+module Net
+  module TNS
+    class DataPacket < Packet
+      register_tns_type 6
+
+      uint16be :flags
+      rest     :data
+
+      def self.max_data_length
+        return Net::TNS::Packet::MAX_PAYLOAD_SIZE - 2   # 2 = flags.length
+      end
+
+      def self.make_disconnect_request
+        packet = self.new()
+        packet.flags = 0x0040
+        return packet
+      end
+    end
+  end
+end

data/lib/net/tns/packets/marker_packet.rb

@@ -0,0 +1,18 @@
+module Net
+  module TNS
+    class MarkerPacket < Packet
+      register_tns_type 12
+
+      uint8    :marker_type
+      rest     :data
+
+      def self.create_request
+        request = self.new
+        request.marker_type = 1
+        request.data = "0002".tns_unhexify
+
+        return request
+      end
+    end
+  end
+end

data/lib/net/tns/packets/null_packet.rb

@@ -0,0 +1,7 @@
+module Net
+  module TNS
+    class NullPacket < Packet
+      register_tns_type 7
+    end
+  end
+end

data/lib/net/tns/packets/redirect_packet.rb

@@ -0,0 +1,10 @@
+module Net
+  module TNS
+    class RedirectPacket < Packet
+      register_tns_type 5
+
+      uint16be :data_length
+      string   :data, :read_length => :data_length
+    end
+  end
+end

data/lib/net/tns/packets/refuse_packet.rb

@@ -0,0 +1,12 @@
+module Net
+  module TNS
+    class RefusePacket < Packet
+      register_tns_type 4
+
+      uint8     :user_reason
+      uint8     :system_reason
+      uint16be  :data_length
+      string    :data, :read_length => :data_length
+    end
+  end
+end

data/lib/net/tns/packets/resend_packet.rb

@@ -0,0 +1,7 @@
+module Net
+  module TNS
+    class ResendPacket < Packet
+      register_tns_type 11
+    end
+  end
+end

data/lib/net/tns/version.rb

@@ -0,0 +1,15 @@
+
+module Net
+  module TNS
+    module Version
+      VERSION_9I = 312
+      VERSION_10G = 313
+      VERSION_11G = 314
+      # Other important versions include:
+      # 308 - The last version before some significant changes to TNS, particularly noticeable in Connect packets
+      # 300 - Many Oracle clients send this as their minimum version
+
+      ALL_VERSIONS = [ VERSION_9I, VERSION_10G, VERSION_11G ]
+    end
+  end
+end

data/lib/net/tns.rb

@@ -0,0 +1,20 @@
+module Net
+  module TNS
+    require "net/tns/packet"
+    require "net/tns/exceptions"
+    require "net/tns/client"
+    require "net/tns/connection"
+    require "net/tns/gem_version"
+    require "net/tns/helpers/string_helpers"
+
+    def self.logger
+      unless defined?(@@logger)
+        require "logger"
+        @@logger = Logger.new(STDERR)
+        @@logger.progname = "Net::TNS"
+        @@logger.sev_threshold = 6 unless $DEBUG
+      end
+      return @@logger
+    end
+  end
+end

data/lib/net/tti/client.rb

@@ -0,0 +1,90 @@
+require "net/tti"
+require "net/tns"
+
+module Net
+  module TTI
+    class Client
+      def connect(opts={})
+        socket_opts = {}
+        socket_opts_keys = [:host, :port]
+        socket_opts_keys.each {|key| socket_opts[key] = opts.delete(key) if opts.has_key?(key)}
+
+        connect_opts = {}
+        connect_opts_keys = [:sid, :service_name]
+        connect_opts_keys.each {|key| connect_opts[key] = opts.delete(key) if opts.has_key?(key)}
+
+        unless opts.empty?
+          raise ArgumentError.new("Unrecognized #connect options: #{opts.keys.join(",")}")
+        end
+
+        begin
+          @tti_conn = Net::TTI::Connection.new(socket_opts)
+          @tti_conn.connect(connect_opts)
+        rescue
+          (@tti_conn.disconnect rescue nil) unless @tti_conn.nil?
+          raise
+        end
+        Net::TTI.logger.info("TTI connection established. #{@tti_conn.conn_params}")
+      end
+
+      def authenticate( username, password )
+        pre_auth_request = get_pre_auth_request( username )
+
+        pre_auth_response_raw = @tti_conn.send_and_receive(pre_auth_request)
+        pre_auth_response = PreAuthenticationResponse.read(pre_auth_response_raw)
+
+        auth_request = get_auth_request(username, password, pre_auth_response)
+
+        begin
+          @tti_conn.send_and_receive(auth_request)
+        rescue Exceptions::ErrorMessageReceived => error
+          case error.error_code
+          when 1017, 9275
+            raise Exceptions::InvalidCredentialsError.new( error.message )
+          when 28000
+            raise Exceptions::AccountLockedOutError.new( error.message )
+          when 28001
+            raise Exceptions::PasswordExpiredError.new( error.message )
+          when 28002
+            # This is "password will expire in 7 days," i.e. a successful login
+          else
+            raise
+          end
+        end
+
+        return true
+      end
+
+      def get_pre_auth_request(username)
+        pre_auth_request = Authentication.create_pre_auth_request( @tti_conn.conn_params.architecture )
+        pre_auth_request.username = username
+        return pre_auth_request
+      end
+
+      def get_auth_request(username, password, pre_auth_response)
+        auth_sesskey = pre_auth_response.auth_sesskey
+
+        case @tti_conn.conn_params.tns_version
+        when Net::TNS::Version::VERSION_10G
+          enc_password, enc_client_session_key = Net::TTI::Crypto.get_10g_auth_values( username, password, auth_sesskey )
+        when Net::TNS::Version::VERSION_11G
+          auth_vfr_data = pre_auth_response.auth_vfr_data
+          enc_password, enc_client_session_key = Net::TTI::Crypto.get_11g_auth_values( password, auth_sesskey, auth_vfr_data )
+        else
+          raise Exceptions::UnsupportedTNSVersion.new( @tti_conn.conn_params.tns_version )
+        end
+
+        auth_request = Authentication.create_auth_request( @tti_conn.conn_params.architecture )
+        auth_request.username = username
+        auth_request.enc_client_session_key = enc_client_session_key
+        auth_request.enc_password = enc_password
+
+        return auth_request
+      end
+
+      def disconnect
+        @tti_conn.disconnect() unless @tti_conn.nil?
+      end
+    end
+  end
+end

data/lib/net/tti/connection.rb

@@ -0,0 +1,142 @@
+require "net/tns"
+require "net/tti/message"
+
+module Net
+  module TTI
+    class ConnectionParameters
+      attr_accessor :platform
+      attr_accessor :architecture
+      attr_accessor :ttc_version
+      attr_accessor :tns_version
+
+      def to_s
+        return "Platform: #{@platform||nil}" +
+          "; Architecture: #{@architecture||nil}" +
+          "; TTC? Version: #{@ttc_version||nil}" +
+          "; TNS Version: #{@tns_version||nil}"
+      end
+    end
+
+    class Connection
+      attr_reader :conn_params
+
+      def initialize(opts={})
+        Net::TTI.logger.debug("Creating new TNS Connection")
+        @tns_connection = Net::TNS::Connection.new(opts)
+        @conn_params = ConnectionParameters.new()
+      end
+
+      def connect(opts={})
+        Net::TTI.logger.debug("Connection#connect called")
+        @tns_connection.connect(opts)
+        @conn_params.tns_version = @tns_connection.tns_protocol_version
+
+        Net::TTI.logger.debug("Sending protocol negotiation request")
+        proto_nego_request = ProtocolNegotiationRequest.create_request()
+        proto_nego_response_raw = send_and_receive( proto_nego_request )
+
+        proto_nego_response = ProtocolNegotiationResponse.read( proto_nego_response_raw )
+        proto_nego_response.populate_connection_parameters( @conn_params )
+
+        Net::TTI.logger.debug("Sending data type negotiation request")
+        dt_nego_request = DataTypeNegotiationRequest.create_request( @conn_params.platform )
+        dt_nego_response_raw = send_and_receive( dt_nego_request )
+
+        return nil
+      end
+
+      def disconnect()
+        @tns_connection.disconnect
+      end
+
+      def send_and_receive( tti_message )
+        send_tti_message(tti_message)
+        receive_tti_message()
+      end
+
+      # Sends a TTI message. This function takes a TTI payload, embeds it in one
+      # or more TNS Data packets and sends those packets.
+      def send_tti_message( tti_message )
+        raw_message = tti_message.to_binary_s
+        Net::TTI.logger.debug( "Connection#send_tti_message called with #{raw_message.length}-byte #{tti_message.class} message" )
+
+        # Split the message into multiple packets if necessary
+        max_data = Net::TNS::DataPacket.max_data_length
+        raw_message.scan(/.{1,#{max_data}}/m).each do |raw_message_part|
+          tns_packet = Net::TNS::DataPacket.new()
+          tns_packet.data = raw_message_part
+          Net::TTI.logger.debug( "Sending data packet (#{tns_packet.num_bytes} bytes total)" )
+          @tns_connection.send_tns_packet( tns_packet )
+        end
+      end
+
+      def receive_tti_message( waiting_for_error_message = false, max_message_length=10_000 )
+        # This is structured as a loop in order to handle messages (e.g. Markers)
+        # that need to be handled without returning to the caller. To keep a malicious
+        # server from making us loop continuously, we set an arbitrary limit of
+        # 10 loops without a "real" message before we throw an exception.
+        receive_count = 0
+        while ( true )
+          receive_count += 1
+          if ( receive_count >= 3 )
+            raise Exceptions::TnsException.new( "Maximum receive attempts exceeded - too many Markers received." )
+          end
+
+          Net::TTI.logger.debug("Attempting to receive packet (try ##{receive_count})")
+          case tns_packet = @tns_connection.receive_tns_packet()
+          when Net::TNS::DataPacket
+            message_data = tns_packet.data
+            # If this is a long packet, the data may have hit the max length and
+            # carried into an additional packet. We wouldn't need to do this if
+            # we could fully parse every message (or at least know lengths to
+            # read). I'm looking at you, DataTypeNegotiationResponse.
+            if tns_packet.num_bytes > 2000
+              begin
+                max_message_length -= message_data.length
+                message_data += receive_tti_message(waiting_for_error_message, max_message_length)
+              rescue Net::TNS::Exceptions::ReceiveTimeoutExceeded
+                Net::TTI.logger.debug("Hit receive timeout trying to read another Data packet")
+              end
+            end
+
+            return message_data
+
+          # We received an error notification
+          when Net::TNS::MarkerPacket
+            Net::TTI.logger.info("Received MarkerPacket")
+            # TNS Markers seem to come in pairs. If we've already got one and sent
+            # the request for the error message, we'll ignore subsequent markers
+            # until we get the error message.
+            unless waiting_for_error_message
+              error_message = get_error_message()
+              raise Exceptions::ErrorMessageReceived.new( error_message )
+            end
+
+          # We received something else
+          else
+            Net::TTI.logger.warn("Received #{tns_packet.class} instead of Data")
+            if waiting_for_error_message
+              raise Exceptions::ProtocolException.new( "Invalid response while waiting for error message - got #{tns_packet.class}" )
+            else
+              raise Exceptions::ProtocolException.new( "Received #{tns_packet.class} instead of TNS data packet (for TTI)" )
+            end
+          end
+        end
+      end
+
+      def get_error_message
+        error_request = Net::TNS::MarkerPacket.create_request()
+        @tns_connection.send_tns_packet( error_request )
+
+        raw_response = receive_tti_message(true)
+        response = Message.from_data_string(raw_response)
+
+        unless response.is_a?(ErrorMessage)
+          raise Exceptions::ProtocolException.new( "Received #{response.class} instead of error message" )
+        end
+
+        return response.message
+      end
+    end
+  end
+end